@uniai-fe/uds-primitives 0.2.0 → 0.2.2

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

@@ -6,23 +6,22 @@ import type {
 import type { HTMLAttributes, MutableRefObject, ReactNode } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
-import type { DropdownRootProps, DropdownSize } from "./base";
+import type {
+  DropdownPanelWidth,
+  DropdownRootProps,
+  DropdownSize,
+} from "./base";
 
 /**
  * Dropdown trigger props
  * @property {boolean} [asChild=true] trigger를 asChild 패턴으로 감쌀지 여부
  */
-export interface DropdownTriggerProps extends DropdownMenuTriggerProps {
-  /**
-   * trigger를 asChild 패턴으로 감쌀지 여부
-   */
-  asChild?: DropdownMenuTriggerProps["asChild"];
-}
+export type DropdownTriggerProps = DropdownMenuTriggerProps;
 
 /**
  * Dropdown Container props
  * @property {DropdownSize} [size="medium"] option 높이 스케일
- * @property {boolean} [matchTriggerWidth=true] trigger 너비에 맞춰 dropdown 너비를 맞출지 여부
+ * @property {DropdownPanelWidth} [width="match"] dropdown panel width 옵션
  * @property {HTMLElement | null} [portalContainer] portal을 렌더링할 DOM 컨테이너
  */
 export interface DropdownContainerProps extends DropdownMenuContentProps {
@@ -33,7 +32,7 @@ export interface DropdownContainerProps extends DropdownMenuContentProps {
   /**
    * trigger 너비에 맞춰 dropdown 너비를 맞출지 여부
    */
-  matchTriggerWidth?: boolean;
+  width?: DropdownPanelWidth;
   /**
    * portal을 렌더링할 DOM 컨테이너
    */
@@ -44,8 +43,8 @@ export interface DropdownContainerProps extends DropdownMenuContentProps {
  * Dropdown menu item props
  * @property {ReactNode} [label] 옵션 라벨
  * @property {ReactNode} [description] 보조 텍스트
- * @property {ReactNode} [leftSlot] 좌측 슬롯
- * @property {ReactNode} [rightSlot] 우측 슬롯
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
  * @property {boolean} [isSelected] 선택 상태 여부
  * @property {boolean} [multiple] multi select 스타일 여부
  * @property {CheckboxProps} [checkboxProps] multiple 시 Checkbox 커스터마이징 옵션
@@ -60,13 +59,13 @@ export interface DropdownMenuItemProps extends RadixDropdownMenuItemProps {
    */
   description?: ReactNode;
   /**
-   * 좌측 슬롯
+   * 좌측 콘텐츠
    */
-  leftSlot?: ReactNode;
+  left?: ReactNode;
   /**
-   * 우측 슬롯
+   * 우측 콘텐츠
    */
-  rightSlot?: ReactNode;
+  right?: ReactNode;
   /**
    * 선택 상태 여부
    */
@@ -103,8 +102,8 @@ export interface DropdownContextValue {
  * @property {ReactNode} label 옵션 라벨
  * @property {ReactNode} [description] 보조 텍스트
  * @property {boolean} [disabled] 비활성 여부
- * @property {ReactNode} [leftSlot] 좌측 슬롯
- * @property {ReactNode} [rightSlot] 우측 슬롯
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
  * @property {boolean} [multiple] multi select 스타일 여부
  */
 export interface DropdownTemplateItem {
@@ -125,13 +124,13 @@ export interface DropdownTemplateItem {
    */
   disabled?: boolean;
   /**
-   * 좌측 슬롯
+   * 좌측 콘텐츠
    */
-  leftSlot?: ReactNode;
+  left?: ReactNode;
   /**
-   * 우측 슬롯
+   * 우측 콘텐츠
    */
-  rightSlot?: ReactNode;
+  right?: ReactNode;
   /**
    * multi select 스타일 여부
    */
@@ -144,7 +143,7 @@ export interface DropdownTemplateItem {
  * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
  * @property {string[]} [selectedIds] 선택된 item id 배열
  * @property {DropdownSize} [size="medium"] surface height scale
- * @property {boolean} [matchTriggerWidth=true] trigger width 동기화 여부
+ * @property {DropdownPanelWidth} [width="match"] panel width 옵션
  * @property {DropdownRootProps} [rootProps] Root 에 전달할 props
  * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
  * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
@@ -155,7 +154,7 @@ export interface DropdownTemplateProps {
   selectedIds?: string[];
   onSelect?: (item: DropdownTemplateItem) => void;
   size?: DropdownSize;
-  matchTriggerWidth?: boolean;
+  width?: DropdownPanelWidth;
   /**
    * Root 에 전달할 props
    */
@@ -163,10 +162,7 @@ export interface DropdownTemplateProps {
   /**
    * Container 에 전달할 props
    */
-  containerProps?: Omit<
-    DropdownContainerProps,
-    "children" | "size" | "matchTriggerWidth"
-  >;
+  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
   /**
    * MenuList 에 전달할 props
    */

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

@@ -1 +1,2 @@
 export { useDigitField } from "./useDigitField";
+export { useAddress, useAddressFields } from "./useAddress";

package/src/components/input/hooks/useAddress.ts

@@ -0,0 +1,247 @@
+"use client";
+
+import { useCallback } from "react";
+import {
+  useDaumPostcodePopup,
+  type Address as DaumAddress,
+} from "react-daum-postcode";
+import { type FieldValues, type Path, useFormContext } from "react-hook-form";
+
+import { createAddressSearchResult } from "../utils/address";
+import type { AddressSelectionOptions } from "../types/address";
+
+type FieldPath = Path<FieldValues>;
+
+interface AddressFieldController {
+  formContext: ReturnType<typeof useFormContext>;
+  addressName?: FieldPath;
+  detailName?: FieldPath;
+  zipCodeName?: FieldPath;
+  setAddressValue: (value: string) => void;
+  setDetailValue: (value: string) => void;
+  clearDetailValue: () => void;
+  setZipCodeValue: (value: string) => void;
+}
+
+const useAddressFieldController = ({
+  addressFieldName,
+  detailFieldName,
+  zipCodeFieldName,
+  triggerValidation,
+}: Pick<
+  AddressSelectionOptions,
+  "addressFieldName" | "detailFieldName" | "zipCodeFieldName"
+> & { triggerValidation: boolean }): AddressFieldController => {
+  const formContext = useFormContext<FieldValues>();
+  const addressName = addressFieldName
+    ? (addressFieldName as FieldPath)
+    : undefined;
+  const detailName = detailFieldName
+    ? (detailFieldName as FieldPath)
+    : undefined;
+  const zipCodeName = zipCodeFieldName
+    ? (zipCodeFieldName as FieldPath)
+    : undefined;
+
+  const setAddressValue = useCallback(
+    (value: string) => {
+      if (!addressName) return;
+      formContext.setValue(addressName, value, {
+        shouldDirty: true,
+        shouldTouch: true,
+        shouldValidate: triggerValidation,
+      });
+    },
+    [addressName, formContext, triggerValidation],
+  );
+
+  const setDetailValue = useCallback(
+    (value: string) => {
+      if (!detailName) return;
+      formContext.setValue(detailName, value, {
+        shouldDirty: true,
+        shouldTouch: true,
+        shouldValidate: triggerValidation,
+      });
+    },
+    [detailName, formContext, triggerValidation],
+  );
+
+  const clearDetailValue = useCallback(() => {
+    setDetailValue("");
+  }, [setDetailValue]);
+
+  const setZipCodeValue = useCallback(
+    (value: string) => {
+      if (!zipCodeName) return;
+      formContext.setValue(zipCodeName, value, {
+        shouldDirty: true,
+        shouldTouch: true,
+        shouldValidate: triggerValidation,
+      });
+    },
+    [formContext, triggerValidation, zipCodeName],
+  );
+
+  return {
+    formContext,
+    addressName,
+    detailName,
+    zipCodeName,
+    setAddressValue,
+    setDetailValue,
+    clearDetailValue,
+    setZipCodeValue,
+  };
+};
+
+/**
+ * 주소 검색 팝업을 열고 선택한 값을 react-hook-form과 콜백에 전달한다.
+ * @hook
+ * @param {AddressSelectionOptions} options 주소 필드 옵션
+ * @desc
+ * - return { openPopup, setAddressValue, setDetailValue, clearDetailValue, setZipCodeValue }
+ * @example
+ * ```tsx
+ * const { openPopup } = useAddress({
+ *   addressFieldName: "farm.address",
+ *   zipCodeFieldName: "farm.zipCode",
+ *   onSelect: (payload) => console.log(payload.address),
+ * });
+ * <Input.Address.Button onClick={openPopup} />
+ * ```
+ */
+export const useAddress = ({
+  addressFieldName,
+  detailFieldName,
+  zipCodeFieldName,
+  triggerValidation = true,
+  resetDetailOnSelect = true,
+  onSelect,
+}: AddressSelectionOptions) => {
+  const openDaumPopup = useDaumPostcodePopup();
+  const { setAddressValue, setDetailValue, clearDetailValue, setZipCodeValue } =
+    useAddressFieldController({
+      addressFieldName,
+      detailFieldName,
+      zipCodeFieldName,
+      triggerValidation,
+    });
+
+  const handleComplete = useCallback(
+    (address: DaumAddress) => {
+      const payload = createAddressSearchResult(address);
+
+      setAddressValue(payload.address);
+      setZipCodeValue(payload.zipCode);
+      if (resetDetailOnSelect) {
+        clearDetailValue();
+      }
+
+      onSelect?.(payload);
+    },
+    [
+      clearDetailValue,
+      onSelect,
+      resetDetailOnSelect,
+      setAddressValue,
+      setZipCodeValue,
+    ],
+  );
+
+  const openPopup = useCallback(() => {
+    openDaumPopup({ onComplete: handleComplete });
+  }, [handleComplete, openDaumPopup]);
+
+  return {
+    /**
+     * 주소 검색 팝업 열기
+     */
+    openPopup,
+    /**
+     * 주소 값을 외부에서 직접 갱신할 때 사용할 setter
+     */
+    setAddressValue,
+    /**
+     * 상세 주소 값을 직접 갱신할 때 사용할 setter
+     */
+    setDetailValue,
+    /**
+     * 상세 주소 값을 초기화한다.
+     */
+    clearDetailValue,
+    /**
+     * 우편번호 값을 직접 갱신할 때 사용할 setter
+     */
+    setZipCodeValue,
+  };
+};
+
+/**
+ * 주소/상세/우편번호 필드 값을 감시하고 제어 메서드를 제공한다.
+ * @hook
+ * @param {AddressSelectionOptions} options 주소 필드 옵션
+ * @desc
+ * - return { addressValue, detailValue, zipCodeValue, setAddressValue, setDetailValue, clearDetailValue, setZipCodeValue }
+ * @example
+ * ```tsx
+ * const {
+ *   addressValue,
+ *   detailValue,
+ *   setDetailValue,
+ * } = useAddressFields({
+ *   addressFieldName: "farm.address",
+ *   detailFieldName: "farm.detailAddress",
+ *   zipCodeFieldName: "farm.zipCode",
+ * });
+ * ```
+ */
+export const useAddressFields = ({
+  addressFieldName,
+  detailFieldName,
+  zipCodeFieldName,
+  triggerValidation = true,
+}: AddressSelectionOptions) => {
+  const controller = useAddressFieldController({
+    addressFieldName,
+    detailFieldName,
+    zipCodeFieldName,
+    triggerValidation,
+  });
+  const {
+    formContext,
+    addressName,
+    detailName,
+    zipCodeName,
+    setAddressValue,
+    setDetailValue,
+    clearDetailValue,
+    setZipCodeValue,
+  } = controller;
+
+  const getStringValue = (value: unknown): string => {
+    if (typeof value === "string") return value;
+    if (value === undefined || value === null) return "";
+    return String(value);
+  };
+
+  const addressValue = addressName
+    ? getStringValue(formContext.watch(addressName))
+    : "";
+  const detailValue = detailName
+    ? getStringValue(formContext.watch(detailName))
+    : "";
+  const zipCodeValue = zipCodeName
+    ? getStringValue(formContext.watch(zipCodeName))
+    : "";
+
+  return {
+    addressValue,
+    detailValue,
+    zipCodeValue,
+    setAddressValue,
+    setDetailValue,
+    clearDetailValue,
+    setZipCodeValue,
+  };
+};

package/src/components/input/index.scss

@@ -1 +1,5 @@
-@use "./styles/index.scss";
+@use "./styles/variables.scss" as inputVariables;
+@use "./styles/foundation.scss" as inputFoundation;
+@use "./styles/text.scss" as inputText;
+@use "./styles/calendar.scss" as inputCalendar;
+@use "./styles/address.scss" as inputAddress;

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%;
+}