@uniai-fe/uds-primitives 0.2.1 → 0.2.2

package/src/components/input/markup/address/Button.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import clsx from "clsx";
+
+import { Button } from "../../../button";
+import type { AddressFindButtonProps } from "../../types/address";
+import { useAddress } from "../../hooks/useAddress";
+
+/**
+ * 주소 찾기 버튼; react-daum-postcode 팝업을 열고 결과를 RHF와 콜백에 전달한다.
+ * @component
+ * @param {AddressFindButtonProps} props 버튼 props
+ * @param {React.ReactNode} [props.label] 버튼 라벨 텍스트
+ * @param {string} [props.className] 커스텀 className
+ * @param {"primary"|"secondary"|"tertiary"} [props.priority="secondary"] 버튼 priority
+ * @param {"solid"|"outlined"} [props.fill="solid"] 버튼 fill 타입
+ * @param {"xlarge"|"large"|"medium"|"small"} [props.size="xlarge"] 버튼 size
+ * @param {"button"|"submit"|"reset"} [props.type="button"] native type
+ * @param {boolean} [props.disabled] disabled 상태
+ * @param {string} [props.addressFieldName] react-hook-form 주소 필드 이름
+ * @param {string} [props.detailFieldName] react-hook-form 상세 주소 필드 이름
+ * @param {string} [props.zipCodeFieldName] react-hook-form 우편번호 필드 이름
+ * @param {boolean} [props.triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @param {boolean} [props.resetDetailOnSelect=true] 새 주소 선택 시 상세 주소 초기화 여부
+ * @param {(payload:AddressSearchResult)=>void} [props.onSelect] 주소 선택 콜백
+ * @example
+ * ```tsx
+ * <Input.Address.Button
+ *   label="검색"
+ *   addressFieldName="farm.address"
+ *   zipCodeFieldName="farm.zipCode"
+ *   onSelect={(payload) => console.log(payload.address)}
+ * />
+ * ```
+ */
+export default function AddressFindButton({
+  label,
+  className,
+  priority = "secondary",
+  fill = "solid",
+  size = "xlarge",
+  type = "button",
+  disabled,
+  ...selectionOptions
+}: AddressFindButtonProps) {
+  // RHF + react-daum-postcode 연결을 위한 팝업 핸들러
+  const { openPopup } = useAddress(selectionOptions);
+
+  return (
+    <Button.Default
+      priority={priority}
+      fill={fill}
+      size={size}
+      type={type}
+      onClick={openPopup}
+      disabled={disabled}
+      className={clsx("input-address-button", className)}
+    >
+      {/* 비어 있는 라벨일 때 기본 문구를 강제로 노출 */}
+      {["string", "number"].includes(typeof label) && label !== ""
+        ? String(label)
+        : (label ?? "검색")}
+    </Button.Default>
+  );
+}

package/src/components/input/markup/address/Template.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import clsx from "clsx";
+import { useEffect } from "react";
+import { useFormContext, type FieldValues, type Path } from "react-hook-form";
+
+import InputBase from "../foundation/Input";
+import type { AddressTemplateProps } from "../../types/address";
+import AddressFindButton from "./Button";
+import { resolveAddressValue } from "../../utils/address";
+
+/**
+ * 주소 입력 템플릿; 주소/상세 입력 필드와 검색 버튼을 조합한다.
+ * @component
+ * @param {AddressTemplateProps} props 템플릿 props
+ * @param {string} [props.className] container className
+ * @param {AddressSharedInputStyleProps} [props.inputStyle] 공유 input 스타일 옵션
+ * @param {InputProps} props.addressInput 주소 입력 필드 props
+ * @param {InputProps} [props.detailInput] 상세 주소 입력 필드 props
+ * @param {AddressTemplateButtonOptions} [props.buttonProps] 검색 버튼 옵션
+ * @param {boolean} [props.disabled] 템플릿 disabled 상태
+ * @param {string} [props.addressFieldName] RHF 주소 필드 네임
+ * @param {string} [props.zipCodeFieldName] RHF 우편번호 필드 네임
+ * @param {boolean} [props.triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @param {(payload:AddressSearchResult)=>void} [props.onSelect] 주소 선택 콜백
+ * @example
+ * ```tsx
+ * <FormProvider {...methods}>
+ *   <Input.Address.Template
+ *     addressFieldName="farm.address"
+ *     zipCodeFieldName="farm.zipCode"
+ *     addressInput={{ placeholder: "주소 검색" }}
+ *     detailInput={{ placeholder: "상세 주소 입력" }}
+ *     buttonProps={{ label: "검색" }}
+ *   />
+ * </FormProvider>
+ * ```
+ */
+export default function AddressFieldTemplate({
+  className,
+  addressInput,
+  detailInput,
+  inputStyle,
+  buttonProps,
+  disabled,
+  addressFieldName,
+  detailFieldName,
+  zipCodeFieldName,
+  triggerValidation,
+  resetDetailOnSelect = true,
+  onSelect,
+}: AddressTemplateProps) {
+  const formContext = useFormContext<FieldValues>();
+  const inputSize = inputStyle?.size ?? "medium";
+
+  const resolvedAddressFieldName = addressFieldName
+    ? (addressFieldName as Path<FieldValues>)
+    : undefined;
+  const resolvedZipFieldName = zipCodeFieldName
+    ? (zipCodeFieldName as Path<FieldValues>)
+    : undefined;
+  const resolvedDetailFieldName = detailFieldName
+    ? (detailFieldName as Path<FieldValues>)
+    : detailInput?.name
+      ? (detailInput.name as Path<FieldValues>)
+      : undefined;
+
+  useEffect(() => {
+    if (resolvedAddressFieldName)
+      formContext.register(resolvedAddressFieldName);
+    if (resolvedZipFieldName) formContext.register(resolvedZipFieldName);
+  }, [formContext, resolvedAddressFieldName, resolvedZipFieldName]);
+
+  const watchedAddress = resolvedAddressFieldName
+    ? formContext.watch(resolvedAddressFieldName)
+    : undefined;
+  // addressInput.value가 지정되면 RHF watch보다 우선 적용해 강제 값 주입을 허용한다.
+  const addressValueSource =
+    addressInput?.value !== undefined ? addressInput.value : watchedAddress;
+  const resolvedAddress = resolveAddressValue(addressValueSource);
+  // detailFieldName 지정 시 RHF register를 자동으로 연결한다.
+  const detailRegister = resolvedDetailFieldName
+    ? formContext.register(resolvedDetailFieldName)
+    : detailInput?.register;
+  const detailName =
+    detailInput?.name ?? detailFieldName ?? resolvedDetailFieldName;
+
+  return (
+    <div className={clsx("input-address-container", className)}>
+      <div className="input-address-row input-address-upper">
+        <InputBase
+          {...inputStyle}
+          {...addressInput}
+          size={inputSize}
+          value={resolvedAddress.text}
+          width="fill"
+          readOnly
+          disabled
+          className="input-address-field input-address-field-base"
+        />
+        <AddressFindButton
+          {...buttonProps}
+          addressFieldName={addressFieldName}
+          detailFieldName={detailFieldName ?? detailInput?.name}
+          zipCodeFieldName={zipCodeFieldName}
+          triggerValidation={triggerValidation}
+          resetDetailOnSelect={resetDetailOnSelect}
+          onSelect={onSelect}
+          className="input-address-button"
+          size={
+            buttonProps?.size ??
+            (inputSize === "large"
+              ? "xlarge"
+              : inputSize === "medium"
+                ? "large"
+                : "medium")
+          }
+          disabled={disabled ?? buttonProps?.disabled}
+        />
+      </div>
+      {detailInput && (
+        <div className="input-address-row input-address-lower">
+          <InputBase
+            {...inputStyle}
+            {...detailInput}
+            register={detailRegister}
+            name={detailName}
+            width="full"
+            className="input-address-field input-address-field-detail"
+          />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/input/markup/address/index.ts

@@ -0,0 +1,9 @@
+"use client";
+
+import AddressFindButton from "./Button";
+import AddressFieldTemplate from "./Template";
+
+export const InputAddress = {
+  Button: AddressFindButton,
+  Template: AddressFieldTemplate,
+};

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

@@ -1,7 +1,7 @@
 "use client";
 
 import clsx from "clsx";
-import type { PointerEvent as ReactPointerEvent } from "react";
+import type { CSSProperties, PointerEvent as ReactPointerEvent } from "react";
 import {
   ChangeEvent,
   FocusEvent,
@@ -14,6 +14,10 @@ import {
   useState,
 } from "react";
 import type { InputProps } from "../../types";
+import {
+  getFormFieldWidthAttr,
+  getFormFieldWidthValue,
+} from "../../../form/utils/form-field";
 
 import InputBaseSideSlot from "./SideSlot";
 import InputBaseUtil from "./Utility";
@@ -56,6 +60,7 @@ const InputBase = forwardRef<HTMLInputElement, InputProps>(
       size = "medium",
       state: stateProp = "default",
       block = false,
+      width,
       left,
       right,
       clear,
@@ -166,6 +171,18 @@ const InputBase = forwardRef<HTMLInputElement, InputProps>(
     };
 
     const inputName = registerName ?? name;
+    const widthAttr =
+      width !== undefined
+        ? getFormFieldWidthAttr(width)
+        : block
+          ? "full"
+          : undefined;
+    const widthValue =
+      width !== undefined ? getFormFieldWidthValue(width) : undefined;
+    const containerStyle: CSSProperties | undefined =
+      widthValue !== undefined
+        ? ({ ["--input-width" as const]: widthValue } as CSSProperties)
+        : undefined;
 
     return (
       <div
@@ -182,6 +199,8 @@ const InputBase = forwardRef<HTMLInputElement, InputProps>(
         data-state={visualState}
         data-block={block ? "true" : undefined}
         {...(simulatedState ? { "data-simulated-state": simulatedState } : {})}
+        data-width={widthAttr}
+        style={containerStyle}
       >
         <div
           className={clsx(

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

@@ -3,9 +3,11 @@
 import { InputFoundation } from "./foundation";
 import { InputText } from "./text";
 import { InputCalendar } from "./calendar";
+import { InputAddress } from "./address";
 
 export const Input = {
   ...InputFoundation,
   Text: InputText,
   Calendar: InputCalendar,
+  Address: InputAddress,
 };

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

@@ -0,0 +1,24 @@
+.input-address-container {
+  width: 100%;
+}
+
+.input-address-row {
+  width: 100%;
+  display: flex;
+  gap: var(--spacing-gap-5);
+}
+
+.input-address-lower {
+  margin-top: var(--spacing-gap-5);
+}
+
+// .input-address-button {
+// }
+
+.input-address-upper {
+  align-items: center;
+}
+
+.input-address-field {
+  width: 100%;
+}

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";