@uniai-fe/uds-primitives 0.2.1 → 0.2.3

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/date.scss" as inputDate;
+@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/date/Template.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import type { ChangeEvent, MouseEvent as ReactMouseEvent } from "react";
+import { forwardRef, useCallback, useMemo } from "react";
+import { useUncontrolled } from "@mantine/hooks";
+import clsx from "clsx";
+import { Calendar } from "../../../calendar";
+import type {
+  InputCalendarProps,
+  InputCalendarTriggerRenderProps,
+} from "../../types";
+import type { CalendarValue } from "../../../calendar";
+import {
+  createEmptyValue,
+  formatTriggerValue,
+  getTodayValue,
+  serializeCalendarValue,
+} from "../../utils/date";
+import InputDateFooterTemplate from "./footer/Template";
+import InputDateTrigger from "./Trigger";
+
+/**
+ * Input Date Template; trigger + calendar 조합.
+ * @component
+ * @param {InputCalendarProps} props
+ * @param {CalendarMode} [props.mode="date"] 날짜/시간 모드
+ * @param {CalendarColumns} [props.columns=1] 동시 노출 달력 수
+ * @param {CalendarValue} [props.value] 제어형 값
+ * @param {CalendarValue} [props.defaultValue] 비제어 초기값
+ * @param {CalendarOnChange} [props.onChange] 값 변경 이벤트
+ * @param {CalendarOnChange} [props.onValueChange] onChange alias
+ * @param {boolean} [props.readOnly] 읽기 전용 여부
+ * @param {boolean} [props.disabled] 비활성화 여부
+ * @param {CalendarDatePickerProps} [props.datePickerProps] Mantine DatePicker 옵션
+ * @param {string} [props.name] form name/RHF name
+ * @param {UseFormRegisterReturn} [props.register] RHF register
+ * @param {string} [props.placeholder="YYYY-MM-DD"] placeholder
+ * @param {ReactNode} [props.header] 패널 header 콘텐츠
+ * @param {ReactNode} [props.footer] 패널 footer 콘텐츠
+ * @param {unknown} [props.timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ * @param {boolean} [props.calendarOpened] calendar 열림 제어 상태
+ * @param {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
+ * @param {string} [props.className] root className
+ * @param {string} [props.id] trigger id
+ * @param {ReactNode} [props.trigger] 커스텀 trigger 슬롯
+ * @param {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
+ */
+const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
+  (
+    {
+      mode = "date",
+      columns = 1,
+      value,
+      defaultValue,
+      onChange,
+      onValueChange,
+      readOnly,
+      disabled,
+      datePickerProps,
+      name,
+      register,
+      placeholder = "YYYY-MM-DD",
+      className,
+      header,
+      footer,
+      calendarOpened,
+      onClick: triggerOnClick,
+      id,
+      trigger,
+      renderTrigger,
+    },
+    ref,
+  ) => {
+    // useUncontrolled로 제어형/비제어 값을 모두 허용한다.
+    const [calendarValue, setCalendarValue] = useUncontrolled<CalendarValue>({
+      value,
+      defaultValue,
+      finalValue: createEmptyValue(),
+      onChange: next => {
+        onChange?.(next as CalendarValue);
+        onValueChange?.(next as CalendarValue);
+      },
+    });
+
+    // react-hook-form register onChange를 수동 호출해 값 직렬화를 맞춘다.
+    const emitRegisterChange = useCallback(
+      (nextValue: CalendarValue) => {
+        if (!register?.onChange) {
+          return;
+        }
+        const serialized = serializeCalendarValue(nextValue);
+        const syntheticEvent = {
+          target: {
+            name: register.name,
+            value: serialized,
+          },
+          currentTarget: {
+            name: register.name,
+            value: serialized,
+          },
+        } as unknown as ChangeEvent<HTMLInputElement>;
+        register.onChange(syntheticEvent);
+      },
+      [register],
+    );
+
+    const updateValue = useCallback(
+      (nextValue: CalendarValue) => {
+        setCalendarValue(nextValue);
+        emitRegisterChange(nextValue);
+      },
+      [emitRegisterChange, setCalendarValue],
+    );
+
+    const triggerValue = useMemo(
+      () => formatTriggerValue(calendarValue) ?? "",
+      [calendarValue],
+    );
+
+    const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
+      triggerOnClick?.(event);
+    };
+
+    const handleCalendarChange = (nextValue: CalendarValue) => {
+      updateValue(nextValue);
+    };
+
+    // footer 미지정 시 기본 FooterTemplate을 연결한다.
+    const footerContent = footer ?? (
+      <InputDateFooterTemplate
+        disabled={disabled}
+        onClear={() => updateValue(createEmptyValue())}
+        onToday={() => updateValue(getTodayValue())}
+      />
+    );
+
+    const triggerRenderProps: InputCalendarTriggerRenderProps = {
+      id,
+      name: name ?? register?.name,
+      placeholder,
+      displayValue: triggerValue,
+      disabled,
+      onClick: handleTriggerClick,
+    };
+
+    const triggerNode = trigger ?? renderTrigger?.(triggerRenderProps) ?? (
+      <InputDateTrigger
+        id={id}
+        name={name ?? register?.name}
+        register={register}
+        placeholder={placeholder}
+        displayValue={triggerValue}
+        disabled={disabled}
+        onClick={handleTriggerClick}
+      />
+    );
+
+    return (
+      <Calendar.Root
+        ref={ref}
+        className={clsx("input-date-field", className)}
+        mode={mode}
+        columns={columns}
+        disabled={disabled}
+        readOnly={readOnly}
+        value={calendarValue}
+        onChange={handleCalendarChange}
+        datePickerProps={datePickerProps}
+        header={header}
+        footer={footerContent}
+        open={calendarOpened}
+      >
+        {triggerNode}
+      </Calendar.Root>
+    );
+  },
+);
+
+InputDateTemplate.displayName = "InputDateTemplate";
+
+export default InputDateTemplate;