@uniai-fe/uds-primitives 0.2.0 → 0.2.2

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

@@ -2,9 +2,35 @@
   display: flex;
   flex-direction: column;
   gap: var(--spacing-gap-3);
-  width: 100%;
+  width: var(--input-width);
+  flex: var(--input-flex);
+  min-width: 0;
+
+  &[data-width="auto"] {
+    --input-width: auto;
+    --input-flex: 0 1 auto;
+  }
+
+  &[data-width="fill"] {
+    --input-width: auto;
+    --input-flex: 1 1 0%;
+  }
+
+  &[data-width="full"],
+  &[data-block="true"] {
+    --input-width: 100%;
+    --input-flex: 0 0 100%;
+  }
+
+  &[data-width="fit"] {
+    --input-width: fit-content;
+    --input-flex: 0 0 auto;
+  }
+
+  &[data-width="custom"] {
+    --input-flex: 0 0 auto;
+  }
 
-  &[data-block="true"],
   &--block {
     width: 100%;
   }

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

@@ -1,4 +1,8 @@
 :root {
+  /* Layout presets */
+  --input-width: 100%;
+  --input-flex: 0 1 auto;
+
   /* Input sizing tokens; Button 변수 규칙과 동일한 prefix 패턴을 맞춘다. */
   --input-default-height-small: var(--theme-size-medium-1);
   --input-default-height-medium: var(--theme-size-medium-2);

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

@@ -0,0 +1,249 @@
+import type { ReactNode } from "react";
+import type { Address } from "react-daum-postcode";
+import type {
+  ButtonFill,
+  ButtonPriority,
+  ButtonSize,
+} from "../../button/types";
+import type { InputProps } from "./foundation";
+
+/**
+ * 주소 문자열/배열 정규화 결과.
+ * @property {string} text 최종 병합된 주소 문자열
+ * @property {string[]} parts 주소를 구성하는 파트 배열
+ */
+export interface AddressResolvedValue {
+  /**
+   * 최종 병합된 주소 문자열
+   */
+  text: string;
+  /**
+   * 주소 파트 배열
+   */
+  parts: string[];
+}
+
+/**
+ * 주소 검색 완료 데이터.
+ * @property {string} address 전체 주소 문자열
+ * @property {string[]} [addressParts] 주소를 구성하는 문자열 배열
+ * @property {AddressStructure} [addressStructure] 주소 구성 정보(기본/추가 파트)
+ * @property {string} zipCode 우편번호(5자리)
+ * @property {string} [buildingName] 건물명
+ * @property {string} [district] 법정동/읍면 정보
+ * @property {Address} raw react-daum-postcode Address 원본 데이터
+ */
+export interface AddressSearchResult {
+  /**
+   * 전체 주소 문자열
+   */
+  address: string;
+  /**
+   * 주소를 구성하는 문자열 배열
+   */
+  addressParts?: string[];
+  /**
+   * 주소 구성 정보(기본 주소 + 추가 파트)
+   */
+  addressStructure?: AddressStructure;
+  /**
+   * 우편번호(5자리)
+   */
+  zipCode: string;
+  /**
+   * 건물명
+   */
+  buildingName?: string;
+  /**
+   * 법정동/읍면 정보
+   */
+  district?: string;
+  /**
+   * react-daum-postcode Address 원본 데이터
+   */
+  raw: Address;
+}
+
+/**
+ * 주소 구성 정보.
+ * @property {string} main 기본 주소
+ * @property {string[]} extras 추가 주소 파트 배열
+ * @example
+ * ```ts
+ * const structure: AddressStructure = {
+ *   main: "서울시 강남구 ...",
+ *   extras: ["도곡동", "OO아파트"],
+ * };
+ * ```
+ */
+export interface AddressStructure {
+  /**
+   * 기본 주소
+   */
+  main: string;
+  /**
+   * 추가 주소 파트 배열
+   */
+  extras: string[];
+}
+
+/**
+ * 주소 선택 처리 공통 옵션.
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [detailFieldName] react-hook-form에 적용할 상세 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {boolean} [resetDetailOnSelect=true] 새 주소 선택 시 상세 주소를 초기화할지 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressSelectionOptions {
+  /**
+   * react-hook-form 주소 필드 이름
+   */
+  addressFieldName?: string;
+  /**
+   * react-hook-form 상세 주소 필드 이름
+   */
+  detailFieldName?: string;
+  /**
+   * react-hook-form 우편번호 필드 이름
+   */
+  zipCodeFieldName?: string;
+  /**
+   * setValue 이후 trigger 실행 여부
+   */
+  triggerValidation?: boolean;
+  /**
+   * 새 주소 선택 시 상세 주소 초기화 여부
+   */
+  resetDetailOnSelect?: boolean;
+  /**
+   * 주소 선택 후 콜백
+   */
+  onSelect?: (payload: AddressSearchResult) => void;
+}
+
+/**
+ * 제한된 입력 스타일 props; priority/size/state/block만 공유한다.
+ */
+export type AddressSharedInputStyleProps = Pick<
+  InputProps,
+  "priority" | "size" | "state"
+>;
+
+/**
+ * 주소 검색 버튼 props.
+ * @property {ReactNode} [children] 버튼 라벨
+ * @property {ButtonPriority} [priority] 버튼 priority
+ * @property {ButtonFill} [fill] 버튼 fill 타입
+ * @property {ButtonSize} [size] 버튼 size
+ * @property {string} [className] 추가 className
+ * @property {"button"|"submit"|"reset"} [type] button type
+ * @property {boolean} [disabled] disabled 여부
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressFindButtonProps extends AddressSelectionOptions {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 버튼 priority
+   */
+  priority?: ButtonPriority;
+  /**
+   * 버튼 fill 타입
+   */
+  fill?: ButtonFill;
+  /**
+   * 버튼 size
+   */
+  size?: ButtonSize;
+  /**
+   * 추가 className
+   */
+  className?: string;
+  /**
+   * button type
+   */
+  type?: "button" | "submit" | "reset";
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+}
+
+/**
+ * 주소 템플릿 버튼 옵션.
+ * @property {ReactNode} [label] 버튼 라벨
+ * @property {ButtonPriority} [priority] 버튼 priority
+ * @property {ButtonFill} [fill] 버튼 fill 타입
+ * @property {ButtonSize} [size] 버튼 size
+ * @property {boolean} [disabled] 버튼 disabled 여부
+ */
+export interface AddressTemplateButtonOptions {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 버튼 priority
+   */
+  priority?: ButtonPriority;
+  /**
+   * 버튼 fill 타입
+   */
+  fill?: ButtonFill;
+  /**
+   * 버튼 size
+   */
+  size?: ButtonSize;
+  /**
+   * 버튼 disabled 여부
+   */
+  disabled?: boolean;
+}
+
+/**
+ * 주소 필드 템플릿 props.
+ * @property {string} [className] container className
+ * @property {AddressSharedInputStyleProps} [inputStyle] 공통 입력 스타일 props
+ * @property {InputProps} addressInput 주소 입력 Input props
+ * @property {InputProps} [detailInput] 상세 주소 입력 props
+ * @property {string} [detailFieldName] react-hook-form에 적용할 상세 주소 필드 이름
+ * @property {AddressTemplateButtonOptions} [buttonProps] 버튼 옵션
+ * @property {boolean} [disabled] 템플릿 disabled 여부
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressTemplateProps extends AddressSelectionOptions {
+  /**
+   * container className
+   */
+  className?: string;
+  /**
+   * 공통 입력 스타일 props
+   */
+  inputStyle?: AddressSharedInputStyleProps;
+  /**
+   * 주소 입력 Input props
+   */
+  addressInput: InputProps;
+  /**
+   * 상세 주소 입력 Input props
+   */
+  detailInput?: InputProps;
+  /**
+   * 버튼 옵션
+   */
+  buttonProps?: AddressTemplateButtonOptions;
+  /**
+   * 템플릿 disabled 여부
+   */
+  disabled?: boolean;
+}

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

@@ -5,6 +5,7 @@ import type {
   ReactNode,
 } from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
+import type { FormFieldWidth } from "../../form/types/props";
 
 /**
  * input; priority option
@@ -99,6 +100,7 @@ export interface InputIcon {
  * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
  * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
  * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ * @property {FormFieldWidth} [width] width preset 옵션
  */
 export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
   /**
@@ -129,6 +131,10 @@ export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
    * react-hook-form register 반환값
    */
   register?: UseFormRegisterReturn;
+  /**
+   * width preset 옵션
+   */
+  width?: FormFieldWidth;
   /**
    * Storybook 등에서 강제 상태 표현용
    */

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

@@ -3,3 +3,4 @@ export type * from "./text";
 export type * from "./calendar";
 export type * from "./verification";
 export type * from "./hooks";
+export type * from "./address";

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

@@ -0,0 +1,165 @@
+import { string as toString } from "@uniai-fe/util-functions";
+import type { Address } from "react-daum-postcode";
+
+import type {
+  AddressResolvedValue,
+  AddressSearchResult,
+  AddressStructure,
+} from "../types/address";
+
+/**
+ * 객체 여부 체크 util.
+ */
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+/**
+ * react-daum-postcode AddressSearchResult 유사 객체인지 검사한다.
+ */
+const isAddressSearchResultLike = (
+  value: unknown,
+): value is Partial<AddressSearchResult> =>
+  isObject(value) && typeof value.address === "string";
+
+/**
+ * AddressStructure 형태인지 검사한다.
+ */
+const isAddressStructureLike = (
+  value: unknown,
+): value is Partial<AddressStructure> =>
+  isObject(value) &&
+  ("main" in value || "extras" in value) &&
+  (typeof value.main === "string" || Array.isArray(value.extras));
+
+/**
+ * 문자열 파트 배열을 안전하게 변환한다.
+ */
+const toAddressParts = (items: unknown[] | undefined): string[] => {
+  if (!Array.isArray(items)) return [];
+  return items
+    .map(item => toString(item, ""))
+    .filter((segment): segment is string => segment.length > 0);
+};
+
+/**
+ * AddressStructure에서 main/extras를 순서대로 병합한다.
+ */
+const mergeStructureParts = (
+  structure: AddressStructure | Partial<AddressStructure>,
+): string[] => {
+  const mainPart =
+    typeof structure.main === "string" ? structure.main : undefined;
+  const extras = toAddressParts(structure.extras);
+  return [mainPart, ...extras].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+};
+
+/**
+ * Template/Base 컴포넌트에서 사용하는 주소 문자열 정규화.
+ * @function
+ * @param {unknown} value RHF watch 값 혹은 addressInput.value override
+ * @returns {AddressResolvedValue} 문자열과 파트 배열
+ */
+export const resolveAddressValue = (value: unknown): AddressResolvedValue => {
+  if (typeof value === "string") {
+    return {
+      text: value,
+      parts: value.length > 0 ? [value] : [],
+    };
+  }
+
+  if (Array.isArray(value)) {
+    const parts = toAddressParts(value);
+    return {
+      text: parts.join(" "),
+      parts,
+    };
+  }
+
+  if (isAddressSearchResultLike(value)) {
+    const base = value.address ?? "";
+    const parts =
+      value.addressParts && value.addressParts.length > 0
+        ? toAddressParts(value.addressParts)
+        : value.addressStructure
+          ? mergeStructureParts(value.addressStructure)
+          : base
+            ? [base]
+            : [];
+    return {
+      text: base,
+      parts,
+    };
+  }
+
+  if (isAddressStructureLike(value)) {
+    const parts = mergeStructureParts(value);
+    return {
+      text: parts.join(" "),
+      parts,
+    };
+  }
+
+  if (isObject(value) && "text" in value) {
+    const textValue =
+      typeof (value as { text?: unknown }).text === "string"
+        ? (value as { text: string }).text
+        : "";
+    const parts = Array.isArray((value as { parts?: unknown[] }).parts)
+      ? toAddressParts((value as { parts: unknown[] }).parts)
+      : textValue
+        ? [textValue]
+        : [];
+    return {
+      text: textValue,
+      parts,
+    };
+  }
+
+  return { text: "", parts: [] };
+};
+
+/**
+ * react-daum-postcode Address 데이터를 AddressSearchResult 형식으로 변환한다.
+ * `address` 필드는 우편번호 서비스에서 내려준 최종 문자열(도로명 + 추가 항목)을 그대로 유지하고,
+ * 분해 정보(`addressParts`, `addressStructure`)를 추가로 제공한다.
+ * @function
+ * @see https://www.juso.go.kr/addrlink/devAddrLinkRequestGuide.do
+ * @param {Address} data 우편번호 서비스 선택 결과
+ * @returns {AddressSearchResult} 변환된 주소 정보 객체
+ * @example
+ * ```ts
+ * const result = createAddressSearchResult(data);
+ * console.log(result.address); // "서울시 강남구 ... (OO동)"
+ * console.log(result.addressParts); // ["서울시 강남구 ...", "OO동"]
+ * ```
+ */
+export const createAddressSearchResult = (
+  data: Address,
+): AddressSearchResult => {
+  const extraParts: string[] = [];
+
+  if (data.addressType === "R") {
+    if (data.bname) extraParts.push(data.bname);
+    if (data.buildingName) extraParts.push(data.buildingName);
+  }
+
+  const baseAddress = data.address;
+  const labelExtras =
+    extraParts.length > 0 ? ` (${extraParts.join(", ")})` : "";
+  const parts = [baseAddress, ...extraParts].filter(part => part.length > 0);
+
+  return {
+    address: `${baseAddress}${labelExtras}`,
+    addressParts: parts,
+    addressStructure: {
+      main: baseAddress,
+      extras: [...extraParts],
+    },
+    zipCode: data.zonecode,
+    buildingName: data.buildingName || undefined,
+    district: data.bname || undefined,
+    raw: data,
+  };
+};

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

@@ -1 +1,2 @@
 export * from "./verification";
+export * from "./address";

package/src/components/radio/markup/Radio.tsx

@@ -26,7 +26,7 @@ const RADIO_HELPER_CLASSNAME = "radio-helper";
  * @example
  * <Radio value="option" />
  */
-export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
+const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
   { size = "medium", className, disabled, ...restProps },
   ref,
 ) {
@@ -49,6 +49,9 @@ export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
   );
 });
 
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+Radio.displayName = "Radio";
+
 /**
  * RadioField component; label/helper wrapper for single radioItem
  * @component
@@ -66,7 +69,7 @@ export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
  * @example
  * <RadioField label="옵션" helperText="필수" value="option" />
  */
-export const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
+const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
   function RadioField(
     {
       label,
@@ -133,3 +136,8 @@ export const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioField.displayName = "RadioField";
+
+export { Radio, RadioField };

package/src/components/radio/markup/RadioCard.tsx

@@ -30,7 +30,7 @@ const RADIO_CARD_INDICATOR_CLASSNAME = "radio-card-indicator";
  * @example
  * <RadioCard title="행복1농장" value="farm-1" />
  */
-export const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
+const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
   function RadioCard(
     {
       title,
@@ -74,3 +74,8 @@ export const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioCard.displayName = "RadioCard";
+
+export { RadioCard };

package/src/components/radio/markup/RadioCardGroup.tsx

@@ -22,7 +22,7 @@ const RADIO_CARD_GROUP_CLASSNAME = "radio-card-group";
  * @example
  * <RadioCardGroup options={[{ id: "farm-1", title: "농장" }]} value="farm-1" />
  */
-export const RadioCardGroup = forwardRef<
+const RadioCardGroup = forwardRef<
   ElementRef<typeof RadixRadioGroup.Root>,
   RadioCardGroupProps
 >(function RadioCardGroup(
@@ -81,3 +81,8 @@ export const RadioCardGroup = forwardRef<
     </RadixRadioGroup.Root>
   );
 });
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioCardGroup.displayName = "RadioCardGroup";
+
+export { RadioCardGroup };

package/src/components/select/markup/Default.tsx

@@ -36,6 +36,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       size = "medium",
       state = "default",
       block,
+      width,
       isOpen,
       disabled,
       buttonType,
@@ -43,7 +44,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       selectedOptionIds,
       onOptionSelect,
       dropdownSize,
-      dropdownMatchTriggerWidth = true,
+      dropdownWidth = "match",
       dropdownRootProps,
       dropdownContainerProps,
       dropdownMenuListProps,
@@ -86,6 +87,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       <Container
         className={clsx("select-trigger-container", className)}
         block={block}
+        width={width}
       >
         <Dropdown.Root
           open={dropdownOpen}
@@ -117,7 +119,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
             <Dropdown.Container
               {...dropdownContainerProps}
               size={panelSize}
-              matchTriggerWidth={dropdownMatchTriggerWidth}
+              width={dropdownWidth}
             >
               <Dropdown.Menu.List {...dropdownMenuListProps}>
                 {/* Dropdown menu option들을 그대로 매핑해 선택 이벤트를 전달한다. */}
@@ -127,8 +129,8 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
                     label={option.label}
                     description={option.description}
                     disabled={option.disabled}
-                    leftSlot={option.leftSlot}
-                    rightSlot={option.rightSlot}
+                    left={option.left}
+                    right={option.right}
                     multiple={Boolean(option.multiple)}
                     isSelected={resolvedSelectedIds.includes(option.id)}
                     onSelect={event => {

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

@@ -3,6 +3,10 @@
 import clsx from "clsx";
 
 import type { SelectContainerProps } from "../../types/props";
+import {
+  getFormFieldWidthAttr,
+  getFormFieldWidthValue,
+} from "../../../form/utils/form-field";
 
 /**
  * Select trigger/container wrapper
@@ -16,12 +20,31 @@ export default function SelectContainer({
   className,
   children,
   block = false,
+  width,
+  style,
+  ...restProps
 }: SelectContainerProps) {
+  const widthAttr =
+    width !== undefined
+      ? getFormFieldWidthAttr(width)
+      : block
+        ? "full"
+        : undefined;
+  const widthValue =
+    width !== undefined ? getFormFieldWidthValue(width) : undefined;
+  const mergedStyle =
+    widthValue !== undefined
+      ? { ...(style ?? {}), ["--select-width" as const]: widthValue }
+      : style;
+
   return (
     <div
       className={clsx("select select-container", className, {
         "select-block": block,
       })}
+      data-width={widthAttr}
+      style={mergedStyle}
+      {...restProps}
     >
       {/** dropdown root 및 dropdown menu 등 포함 예정 */}
       {children}