@uniai-fe/uds-primitives 0.2.1 → 0.2.2

package/dist/styles.css

@@ -11,6 +11,9 @@
   --theme-badge-line-height: var(--font-caption-medium-line-height, 1.5);
   --theme-badge-letter-spacing: var(--font-caption-medium-letter-spacing, 0);
   --theme-badge-dot-size: var(--spacing-gap-3, 8px);
+  /* layout presets */
+  --button-width: fit-content;
+  --button-flex: 0 0 auto;
   /* default button spacing (size 기반) */
   --button-default-gap-small: var(--spacing-gap-1);
   --button-default-gap-medium: var(--spacing-gap-2);
@@ -225,6 +228,9 @@
   --dropdown-option-height-small: var(--theme-size-medium-1, 40px);
   --dropdown-option-height-medium: var(--theme-size-medium-2, 48px);
   --dropdown-option-height-large: var(--theme-size-medium-3, 56px);
+  /* 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);
@@ -260,6 +266,9 @@
   --input-surface-color: var(--color-common-100);
   --input-surface-muted-color: var(--color-neutral-99);
   --input-surface-disabled-color: var(--color-neutral-95);
+  /* layout presets */
+  --select-width: 100%;
+  --select-flex: 0 1 auto;
   --select-primary-height-small: var(--input-default-height-small);
   --select-primary-height-medium: var(--input-default-height-medium);
   --select-primary-height-large: var(--input-default-height-large);
@@ -644,7 +653,8 @@
   align-items: center;
   justify-content: center;
   gap: var(--button-default-gap-medium, var(--spacing-gap-2, 8px));
-  width: fit-content;
+  width: var(--button-width);
+  flex: var(--button-flex);
   min-width: var(--button-default-width-min-base, var(--theme-size-small-2, 24px));
   min-height: var(--button-min-height, auto);
   padding-inline: var(--button-padding-inline, var(--button-default-padding-inline-base, var(--spacing-padding-4, 16px)));
@@ -672,8 +682,24 @@
   align-items: center;
   justify-content: center;
 }
-.button.button-block {
-  width: 100%;
+.button[data-width=auto] {
+  --button-width: auto;
+  --button-flex: 0 1 auto;
+}
+.button[data-width=fill] {
+  --button-width: auto;
+  --button-flex: 1 1 0%;
+}
+.button[data-width=full], .button.button-block {
+  --button-width: 100%;
+  --button-flex: 0 0 100%;
+}
+.button[data-width=fit] {
+  --button-width: fit-content;
+  --button-flex: 0 0 auto;
+}
+.button[data-width=custom] {
+  --button-flex: 0 0 auto;
 }
 .button:not(.button-fill-solid):not(.button-fill-outlined) {
   background-color: transparent;
@@ -1603,9 +1629,30 @@ figure.chip {
   display: flex;
   flex-direction: column;
   gap: var(--spacing-gap-3);
-  width: 100%;
+  width: var(--input-width);
+  flex: var(--input-flex);
+  min-width: 0;
+}
+.input[data-width=auto] {
+  --input-width: auto;
+  --input-flex: 0 1 auto;
+}
+.input[data-width=fill] {
+  --input-width: auto;
+  --input-flex: 1 1 0%;
 }
-.input[data-block=true], .input--block {
+.input[data-width=full], .input[data-block=true] {
+  --input-width: 100%;
+  --input-flex: 0 0 100%;
+}
+.input[data-width=fit] {
+  --input-width: fit-content;
+  --input-flex: 0 0 auto;
+}
+.input[data-width=custom] {
+  --input-flex: 0 0 auto;
+}
+.input--block {
   width: 100%;
 }
 
@@ -2079,18 +2126,63 @@ figure.chip {
   width: 100%;
 }
 
+.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-upper {
+  align-items: center;
+}
+
+.input-address-field {
+  width: 100%;
+}
+
 /* Select tokens mapped to Input primary tokens for visual parity */
 
 
 .select {
   display: flex;
-  width: 100%;
+  width: var(--select-width);
+  flex: var(--select-flex);
   flex-direction: column;
   gap: var(--spacing-gap-2);
+  min-width: 0;
+}
+
+.select[data-width=auto] {
+  --select-width: auto;
+  --select-flex: 0 1 auto;
+}
+
+.select[data-width=fill] {
+  --select-width: auto;
+  --select-flex: 1 1 0%;
 }
 
+.select[data-width=full],
 .select-block {
-  width: 100%;
+  --select-width: 100%;
+  --select-flex: 0 0 100%;
+}
+
+.select[data-width=fit] {
+  --select-width: fit-content;
+  --select-flex: 0 0 auto;
+}
+
+.select[data-width=custom] {
+  --select-flex: 0 0 auto;
 }
 
 .select-button {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -58,7 +58,8 @@
     "@uniai-fe/util-functions": "^0.2.3",
     "react": "^19",
     "react-dom": "^19",
-    "react-hook-form": "^7"
+    "react-hook-form": "^7",
+    "react-daum-postcode": "^3"
   },
   "dependencies": {
     "@mantine/dates": "^8.3.14",
@@ -68,7 +69,8 @@
     "@radix-ui/react-radio-group": "^1.3.8",
     "@radix-ui/react-tabs": "^1.1.13",
     "clsx": "^2.1.1",
-    "dayjs": "^1.11.19"
+    "dayjs": "^1.11.19",
+    "react-daum-postcode": "^3.2.0"
   },
   "devDependencies": {
     "@radix-ui/react-visually-hidden": "^1.2.4",

package/src/components/button/index.tsx

@@ -5,8 +5,6 @@ import "./index.scss";
 
 import { ButtonDefault, ButtonText, ButtonRounded } from "./markup";
 
-export { ButtonDefault, ButtonText, ButtonRounded };
-
 export const Button = {
   Default: ButtonDefault,
   Text: ButtonText,

package/src/components/button/markup/Base.tsx

@@ -4,6 +4,10 @@ import clsx from "clsx";
 import { forwardRef } from "react";
 import type { ButtonProps } from "../types";
 import { SlotComponent } from "../../slot";
+import {
+  getFormFieldWidthAttr,
+  getFormFieldWidthValue,
+} from "../../form/utils/form-field";
 
 /**
  * uds-foundation 토큰 위에서 block/layout/priority/slot API를 제공하는 기본 Button 컴포넌트.
@@ -41,6 +45,7 @@ const ButtonDefault = forwardRef<HTMLElement, ButtonProps>(
       priority,
       state: stateProp = "default",
       block = false,
+      width,
       loading = false,
       className,
       type: typeProp,
@@ -65,6 +70,20 @@ const ButtonDefault = forwardRef<HTMLElement, ButtonProps>(
             "aria-disabled": isDisabled || undefined,
           };
 
+    const widthAttr =
+      width !== undefined
+        ? getFormFieldWidthAttr(width)
+        : block
+          ? "full"
+          : undefined;
+    const widthValue =
+      width !== undefined ? getFormFieldWidthValue(width) : undefined;
+    const { style, ...elementRestProps } = restProps;
+    const mergedStyle =
+      widthValue !== undefined
+        ? { ...(style ?? {}), ["--button-width" as const]: widthValue }
+        : style;
+
     return (
       <SlotComponent
         className={clsx(
@@ -83,8 +102,10 @@ const ButtonDefault = forwardRef<HTMLElement, ButtonProps>(
         ref={forwardedRef}
         aria-busy={loading || undefined}
         data-user-action={userAction}
+        data-width={widthAttr}
+        style={mergedStyle}
         {...elementSpecificProps}
-        {...restProps}
+        {...elementRestProps}
       >
         {left && (
           <span className="button-left" data-slot="left">

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

@@ -150,7 +150,8 @@ $button-priorities: (
   align-items: center;
   justify-content: center;
   gap: var(--button-default-gap-medium, var(--spacing-gap-2, 8px));
-  width: fit-content;
+  width: var(--button-width);
+  flex: var(--button-flex);
   min-width: var(
     --button-default-width-min-base,
     var(--theme-size-small-2, 24px)
@@ -216,8 +217,29 @@ $button-priorities: (
     justify-content: center;
   }
 
+  &[data-width="auto"] {
+    --button-width: auto;
+    --button-flex: 0 1 auto;
+  }
+
+  &[data-width="fill"] {
+    --button-width: auto;
+    --button-flex: 1 1 0%;
+  }
+
+  &[data-width="full"],
   &.button-block {
-    width: 100%;
+    --button-width: 100%;
+    --button-flex: 0 0 100%;
+  }
+
+  &[data-width="fit"] {
+    --button-width: fit-content;
+    --button-flex: 0 0 auto;
+  }
+
+  &[data-width="custom"] {
+    --button-flex: 0 0 auto;
   }
 
   &:not(.button-fill-solid):not(.button-fill-outlined) {

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

@@ -1,5 +1,9 @@
 /* 버튼 전용 토큰은 theme root에서 한 번만 정의하며, size 기반 규칙(--button-{type}-{property}-{size})을 따른다. */
 :root {
+  /* layout presets */
+  --button-width: fit-content;
+  --button-flex: 0 0 auto;
+
   /* default button spacing (size 기반) */
   --button-default-gap-small: var(--spacing-gap-1);
   --button-default-gap-medium: var(--spacing-gap-2);

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

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import type { FormFieldWidth } from "../../form/types";
 
 /**
  * Button; priority 옵션
@@ -91,6 +92,7 @@ type SharedElementProps = Omit<NativeButtonProps, "children"> &
  * @property {ButtonPriority} priority semantic color priority.
  * @property {ButtonState} [state] UI 상태. disabled prop과 조합된다.
  * @property {boolean} [block] width:100% 확장 여부.
+ * @property {FormFieldWidth} [width] width preset. block보다 우선 적용된다.
  * @property {boolean} [loading] true면 readonly 처리 + aria-busy.
  * @property {ReactNode} [left] 라벨 왼쪽 커스텀 슬롯.
  * @property {ReactNode} [right] 라벨 오른쪽 커스텀 슬롯.
@@ -145,6 +147,11 @@ export interface ButtonProps extends SharedElementProps {
    * true면 버튼 폭을 100%로 확장한다.
    */
   block?: boolean;
+  /**
+   * width preset.
+   * block보다 우선 적용된다.
+   */
+  width?: FormFieldWidth;
   /**
    * true면 readonly 상태로 전환하고 aria-busy를 설정한다.
    */

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

@@ -31,31 +31,32 @@ const getIndicatorIcon = (size: CheckboxSize) =>
  * @example
  * <Checkbox size="medium" checked />
  */
-export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
-  function Checkbox(
-    { size = "medium", className, disabled, ...restProps },
-    ref,
-  ) {
-    const IndicatorIcon = getIndicatorIcon(size);
+const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(function Checkbox(
+  { size = "medium", className, disabled, ...restProps },
+  ref,
+) {
+  const IndicatorIcon = getIndicatorIcon(size);
 
-    return (
-      <CheckboxPrimitive.Root
-        ref={ref}
-        disabled={disabled}
-        data-size={size}
-        data-disabled={disabled ? "true" : undefined}
-        className={clsx(CHECKBOX_CLASSNAME, className)}
-        {...restProps}
-      >
-        <span className={CHECKBOX_SURFACE_CLASSNAME} aria-hidden="true">
-          <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
-            <IndicatorIcon aria-hidden />
-          </CheckboxPrimitive.Indicator>
-        </span>
-      </CheckboxPrimitive.Root>
-    );
-  },
-);
+  return (
+    <CheckboxPrimitive.Root
+      ref={ref}
+      disabled={disabled}
+      data-size={size}
+      data-disabled={disabled ? "true" : undefined}
+      className={clsx(CHECKBOX_CLASSNAME, className)}
+      {...restProps}
+    >
+      <span className={CHECKBOX_SURFACE_CLASSNAME} aria-hidden="true">
+        <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
+          <IndicatorIcon aria-hidden />
+        </CheckboxPrimitive.Indicator>
+      </span>
+    </CheckboxPrimitive.Root>
+  );
+});
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+Checkbox.displayName = "Checkbox";
 
 /**
  * 체크박스 필드 컴포넌트; label/helper 텍스트 래퍼
@@ -76,7 +77,7 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
  * @example
  * <CheckboxField label="약관 동의" helperText="필수" checked />
  */
-export const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
+const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
   function CheckboxField(
     {
       label,
@@ -146,3 +147,8 @@ export const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+CheckboxField.displayName = "CheckboxField";
+
+export { Checkbox, CheckboxField };

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

@@ -2,7 +2,16 @@ import { DropdownFoundation } from "./foundation";
 import DropdownTemplate from "./Template";
 
 /**
- * Dropdown namespace export
+ * Dropdown
+ * - Provider
+ * - Root
+ * - Container
+ * - Menu
+ *     - Item
+ *     - List
+ * - Panel
+ * - Trigger
+ * - Template
  */
 export const Dropdown = {
   ...DropdownFoundation,

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;