@ehfuse/mui-form-controls 3.1.20 → 3.1.22

package/README.md

@@ -16,8 +16,9 @@ MUI 기반 폼 컨트롤과 텍스트 필드 컴포넌트 모음
 | **DateTimeTextField**         | 날짜 + 시간 입력 필드                                            | [API](./docs/ko/api.md#datetimetextfield)         |
 | **EmailTextField**            | 도메인 자동완성, 유효성 검사 기능이 있는 이메일 필드             | [API](./docs/ko/api.md#emailtextfield)            |
 | **JuminTextField**            | 주민등록번호 입력 필드 (마스킹, 정보 추출)                       | [API](./docs/ko/api.md#jumintextfield)            |
-| **NumberField**               | 숫자 입력 (`default` 스피너 / `stepper` 가로 스테퍼, 길게 누르기 가속) | [API](./docs/ko/api.md#numberfield)               |
-| **NumberSpinner**             | 숫자 스피너                                                      | [API](./docs/ko/api.md#numberspinner)             |
+| **NumberField**               | 숫자 입력 (MUI OutlinedInput + 위·아래 스피너)                  | [API](./docs/ko/api.md#numberfield)               |
+| **NumberStepper**             | 가로 스테퍼 (`[-]` 숫자 `[+]`, 길게 누르기 가속)                 | [API](./docs/ko/api.md#numberstepper)             |
+| **NumberSpinner**             | 숫자 스피너 (좌우 버튼 + 라벨 드래그)                            | [API](./docs/ko/api.md#numberspinner)             |
 | **NumberTextField**           | 천 단위 구분자, 소수점, 음수 지원하는 숫자 필드                  | [API](./docs/ko/api.md#numbertextfield)           |
 | **PasswordTextField**         | 비밀번호 보기/숨기기 토글, 유효성 검사 기능이 있는 비밀번호 필드 | [API](./docs/ko/api.md#passwordtextfield)         |
 | **PhoneTextField**            | 자동 포맷팅, prefix 고정 기능이 있는 전화번호 필드               | [API](./docs/ko/api.md#phonetextfield)            |
@@ -102,6 +103,7 @@ import {
   ButtonGroup,
   Stepper,
   NumberField,
+  NumberStepper,
   NumberSpinner,
   LabelSelect,
   Autocomplete,
@@ -292,25 +294,32 @@ import { AddressTextField } from '@ehfuse/mui-form-controls/address';
 
 `draggable`이 `true`이면 짧은 클릭과 드래그 시작이 겹칠 수 있습니다(기본 포인터 센서는 약 5px 이동 후 드래그). 자세한 props는 [한국어 API](./docs/ko/api.md#tagstextfield)를 참고하세요.
 
-## NumberField
+## NumberField · NumberStepper · NumberSpinner
 
-기본은 MUI OutlinedInput + 위·아래 스피너입니다. `variant="stepper"`는 장바구니 수량처럼 `[-]` 숫자 `[+]` 가로 UI입니다.
+세 컴포넌트는 공용 훅 `useNumberBasic`을 기반으로 동일한 동작 규칙을 공유합니다.
+
+- 입력 중 `min`/`max` 초과 시 **즉시 경계값으로 고정** (clamp)
+- 천 단위 구분은 기본 적용(Intl·로케일), `thousandSeparator={false}`로 끔
+- `form`/`name` 지정 시 폼 연동
+- `clearWhenZero`로 0을 빈칸 표시 (**기본 `false` — 0을 0으로 표시**)
+
+표시 형태만 다릅니다.
+
+| 컴포넌트 | 형태 |
+| -------- | ---- |
+| **NumberField** | MUI OutlinedInput + 오른쪽 위·아래 스피너 |
+| **NumberStepper** | `[-]` 숫자 `[+]` 가로 스테퍼 (길게 누르기 가속) |
+| **NumberSpinner** | 좌우 `[-]`/`[+]` 버튼 + 라벨 드래그(scrub) 증감 |
 
 ```tsx
-// 기본 스피너
+// NumberField — 기본 입력 + 위·아래 스피너
 <NumberField label="수량" defaultValue={2} min={0} max={99} />
 
-// 천 단위 구분은 기본 적용(Intl·로케일). 끄려면 thousandSeparator={false}
-<NumberField
-  label="금액"
-  defaultValue={1234567}
-  min={0}
-  max={99999999}
-/>
+// 천 단위 구분은 기본 적용. 끄려면 thousandSeparator={false}
+<NumberField label="금액" defaultValue={1234567} min={0} max={99999999} />
 
-// 가로 스테퍼 + 길게 누르기 가속 (CPS = 초당 클릭/증감 횟수)
-<NumberField
-  variant="stepper"
+// NumberStepper — 가로 스테퍼 + 길게 누르기 가속 (CPS = 초당 증감 횟수)
+<NumberStepper
   defaultValue={1}
   min={0}
   max={99}
@@ -320,16 +329,20 @@ import { AddressTextField } from '@ehfuse/mui-form-controls/address';
   stepperAccelerateCps={5}
   stepperAccelerateMaxCps={25}
 />
+
+// NumberSpinner — 좌우 버튼 + 라벨 드래그
+<NumberSpinner label="수량" defaultValue={2} min={0} max={99} />
 ```
 
 | prop | 설명 |
 | ---- | ---- |
-| `stepperAccelerateHoldDelay` | 누른 직후 1회 변경 후, 자동 반복까지 대기(ms) |
-| `stepperAccelerateRampDuration` | 시작 CPS→최대 CPS까지 걸리는 시간(ms) |
-| `stepperAccelerateCps` | 자동 반복 **시작** 속도 (초당 횟수) |
-| `thousandSeparator` | `boolean \| string` — 기본 `true`. `false` 끔 · `string` 구분 문자 고정 · NumberField는 `true`일 때 Intl |
+| `thousandSeparator` | `boolean \| string` — 기본 `true`. `false` 끔 · `string` 구분 문자 고정 · `true`일 때 Intl |
+| `clearWhenZero` | 0을 빈칸으로 표시. 기본 `false` |
+| `stepperAccelerateHoldDelay` | (NumberStepper) 누른 직후 1회 변경 후, 자동 반복까지 대기(ms) |
+| `stepperAccelerateRampDuration` | (NumberStepper) 시작 CPS→최대 CPS까지 걸리는 시간(ms) |
+| `stepperAccelerateCps` | (NumberStepper) 자동 반복 **시작** 속도 (초당 횟수) |
 
-`stepperEditable`, `stepperButtonDivider`, `spinnerDivider` 등 전체 props는 [API](./docs/ko/api.md#numberfield)를 참고하세요.
+`stepperEditable`, `stepperButtonDivider`(NumberStepper), `spinnerDivider`(NumberField) 등 전체 props는 [API](./docs/ko/api.md#numberfield)를 참고하세요.
 
 ## Boolean 필드 표준 패턴
 

package/dist/NumberField.d.ts

@@ -6,5 +6,8 @@
  * @author 김영진 (ehfuse@gmail.com)
  */
 export { default as NumberField } from "./components/NumberField";
-export type { NumberFieldAlign, NumberFieldProps, NumberFieldVariant, } from "./components/NumberField";
+export type { NumberFieldAlign, NumberFieldProps, } from "./components/NumberField";
+export { default as NumberStepper } from "./components/NumberStepper";
+export type { NumberStepperProps } from "./components/NumberStepper";
 export { default as NumberSpinner } from "./components/NumberSpinner";
+export type { NumberSpinnerProps } from "./components/NumberSpinner";

package/dist/components/NumberField.d.ts

@@ -1,101 +1,21 @@
-import * as React from "react";
-import { NumberField as BaseNumberField } from "@base-ui/react/number-field";
-import type { SxProps, Theme } from "@mui/material/styles";
-import type { FormLike } from "../types";
-import { type ThousandSeparatorProp } from "../utils/number";
-export type NumberFieldVariant = "default" | "stepper";
-export type NumberFieldAlign = "left" | "center" | "right";
-export type NumberFieldProps = BaseNumberField.Root.Props & {
-    label?: React.ReactNode;
-    size?: "small" | "medium";
-    error?: boolean;
-    fullWidth?: boolean;
-    form?: FormLike | null;
-    suffix?: React.ReactNode;
-    /** 입력 숫자 텍스트 정렬 방향. */
-    align?: NumberFieldAlign;
-    /**
-     * 천 단위 구분.
-     * - `false`: 구분 없음
-     * - `true` / `undefined`(기본): `Intl` 로케일 규칙 (`locale`·`format`과 함께)
-     * - `string`: 구분 문자 직접 지정 (예: `","`, `"."`, `" "`)
-     * @default true
-     */
-    thousandSeparator?: ThousandSeparatorProp;
-    /** @default "default" — `stepper`는 [-] 값 [+] 가로 스테퍼 UI */
-    variant?: NumberFieldVariant;
-    /**
-     * 값이 정확히 0일 때 입력칸을 빈칸으로 표시한다 (placeholder만 노출).
-     *
-     * 내부 값은 항상 숫자(0 포함)로 유지되므로 base-ui의 스피너 증감이 정상 동작한다
-     * (빈칸=0에서 ▲ → 1, 1에서 ▼ → 0=빈칸). 표시(렌더링)만 비우며,
-     * `onValueChange`로는 숫자 0이 그대로 전달된다. 포커스/입력 중에는 사용자가
-     * 타이핑한 값을 그대로 보여주고, 비포커스 상태에서만 0을 빈칸으로 표시한다.
-     *
-     * `default`·`stepper` 두 variant 모두에 적용된다.
-     * 0을 그대로 `0`으로 표시하려면 `clearWhenZero={false}`로 끈다.
-     * @default true
-     */
-    clearWhenZero?: boolean;
-    /**
-     * `variant="stepper"`일 때 가운데를 키패드·키보드로 직접 입력할지 여부.
-     * @default false — Typography로 숫자만 표시 (장바구니 수량 UI 등)
-     */
-    stepperEditable?: boolean;
-    /** `variant="stepper"` 루트(Box)에 적용할 `sx` */
-    stepperSx?: SxProps<Theme>;
-    /** `variant="stepper"`일 때 − / + 버튼과 숫자 영역 사이 세로 구분선 */
-    stepperButtonDivider?: boolean;
-    /** `variant="stepper"` 감소(−) 버튼 `sx` */
-    stepperDecrementButtonSx?: SxProps<Theme>;
-    /** `variant="stepper"` 증가(+) 버튼 `sx` */
-    stepperIncrementButtonSx?: SxProps<Theme>;
-    /** `variant="stepper"` 가운데 숫자 영역 `sx` */
-    stepperCenterSx?: SxProps<Theme>;
-    /**
-     * `variant="stepper"`일 때 화면에 라벨을 표시할지 여부.
-     * @default false — 장바구니 수량처럼 컴팩트 UI에는 라벨 없음. `label`은 접근성용 aria-label로만 쓸 수 있음.
-     */
-    stepperShowLabel?: boolean;
-    /** `variant="stepper"` 감소 버튼 아이콘. 미지정 시 Remove(−) 아이콘 */
-    stepperDecrementIcon?: React.ReactNode;
-    /** `variant="stepper"` 증가 버튼 아이콘. 미지정 시 Add(+) 아이콘 */
-    stepperIncrementIcon?: React.ReactNode;
-    /** `variant="stepper"` 감소 버튼 클릭 이벤트. `event.preventDefault()` 호출 시 기본 감소 동작을 막는다. */
-    onStepperDecrementClick?: (event: React.MouseEvent<HTMLButtonElement>, value: number | null) => void;
-    /** `variant="stepper"` 증가 버튼 클릭 이벤트. `event.preventDefault()` 호출 시 기본 증가 동작을 막는다. */
-    onStepperIncrementClick?: (event: React.MouseEvent<HTMLButtonElement>, value: number | null) => void;
-    /**
-     * `variant="default"`일 때 위·아래 스피너 영역 왼쪽 구분선 표시 여부.
+/**
+ * NumberField.tsx
+ *
+ * MUI OutlinedInput + Base UI NumberField 기반 숫자 입력 필드.
+ * 가로 스테퍼(−값+)는 `NumberStepper`, 드래그 스피너는 `NumberSpinner`로 분리됐다.
+ * 값 상태·clamp·grouping 공용 로직은 `useNumberBasic` 훅이 담당한다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import { type NumberBaseProps } from "./numberBasic";
+export type { NumberFieldAlign } from "./numberBasic";
+export type NumberFieldProps = NumberBaseProps & {
+    /**
+     * 위·아래 스피너 영역 왼쪽 구분선 표시 여부.
      * @default true
      */
     spinnerDivider?: boolean;
-    /**
-     * `variant="stepper"`에서 길게 누를 때 반복 간격이 점점 짧아지는 가속 효과.
-     * @default true
-     */
-    stepperAccelerate?: boolean;
-    /**
-     * 길게 누른 뒤, 숫자가 **한 번** 바뀐 다음 자동 반복이 시작되기까지의 대기 시간(ms).
-     * @default 300
-     */
-    stepperAccelerateHoldDelay?: number;
-    /**
-     * 자동 반복이 시작된 뒤, 시작 속도에서 최고 속도까지 빨라지는 데 걸리는 시간(ms).
-     * @default 1800
-     */
-    stepperAccelerateRampDuration?: number;
-    /**
-     * 길게 눌렀을 때 **처음** 자동으로 숫자가 바뀌는 속도
-     * 예) `5` → 1초에 5번(약 0.2초마다 1씩 증가)
-     * @default 5
-     */
-    stepperAccelerateCps?: number;
-    /**
-     * 가속이 끝난 뒤 유지되는 **최고** 속도.
-     * 예) `100` → 1초에 100번 반복 (약 0.01초마다 1씩 증가)
-     * @default 100
-     */
-    stepperAccelerateMaxCps?: number;
 };
 export default function NumberField(props: NumberFieldProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/NumberSpinner.d.ts

@@ -1,16 +1,14 @@
-import * as React from "react";
-import { NumberField as BaseNumberField } from "@base-ui/react/number-field";
-import { type ThousandSeparatorProp } from "../utils/number";
-type NumberSpinnerProps = BaseNumberField.Root.Props & {
-    label?: React.ReactNode;
-    size?: "small" | "medium";
-    error?: boolean;
-    suffix?: React.ReactNode;
-    /**
-     * 천 단위 구분자(표시·입력, `Intl.NumberFormat`). `true`이면 `format.useGrouping: true` 병합.
-     * @default true — `string`이면 해당 문자로 그룹
-     */
-    thousandSeparator?: ThousandSeparatorProp;
-};
-export default function NumberSpinner({ id: idProp, label, error, size, suffix, thousandSeparator, locale, format, ...other }: NumberSpinnerProps): import("react/jsx-runtime").JSX.Element;
-export {};
+/**
+ * NumberSpinner.tsx
+ *
+ * 좌우 [−][+] 버튼 + 라벨 드래그(ScrubArea) 증감형 숫자 입력.
+ * 값 상태·min/max 즉시 clamp·grouping·폼 연동 공용 로직은 `useNumberBasic` 훅이
+ * 담당한다(min/max·form이 주어졌을 때만 동작하므로 기존 사용과 호환).
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import { type NumberBaseProps } from "./numberBasic";
+export type NumberSpinnerProps = NumberBaseProps;
+export default function NumberSpinner(props: NumberSpinnerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/NumberStepper.d.ts

@@ -0,0 +1,72 @@
+/**
+ * NumberStepper.tsx
+ *
+ * 가로 스테퍼([−] 값 [+]) 형태의 숫자 입력. 장바구니 수량 등 컴팩트 UI용.
+ * 값 상태·clamp·grouping 공용 로직은 `useNumberBasic` 훅이 담당한다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import * as React from "react";
+import type { SxProps, Theme } from "@mui/material/styles";
+import { type NumberBaseProps } from "./numberBasic";
+export type { NumberFieldAlign } from "./numberBasic";
+export type NumberStepperProps = NumberBaseProps & {
+    /**
+     * 가운데를 키패드·키보드로 직접 입력할지 여부.
+     * @default false — Typography로 숫자만 표시 (장바구니 수량 UI 등)
+     */
+    stepperEditable?: boolean;
+    /** 루트(Box)에 적용할 `sx` */
+    stepperSx?: SxProps<Theme>;
+    /** − / + 버튼과 숫자 영역 사이 세로 구분선 */
+    stepperButtonDivider?: boolean;
+    /** 감소(−) 버튼 `sx` */
+    stepperDecrementButtonSx?: SxProps<Theme>;
+    /** 증가(+) 버튼 `sx` */
+    stepperIncrementButtonSx?: SxProps<Theme>;
+    /** 가운데 숫자 영역 `sx` */
+    stepperCenterSx?: SxProps<Theme>;
+    /**
+     * 화면에 라벨을 표시할지 여부.
+     * @default false — 컴팩트 UI에는 라벨 없음. `label`은 aria-label로만 쓸 수 있음.
+     */
+    stepperShowLabel?: boolean;
+    /** 감소 버튼 아이콘. 미지정 시 Remove(−) 아이콘 */
+    stepperDecrementIcon?: React.ReactNode;
+    /** 증가 버튼 아이콘. 미지정 시 Add(+) 아이콘 */
+    stepperIncrementIcon?: React.ReactNode;
+    /** 감소 버튼 클릭 이벤트. `event.preventDefault()` 호출 시 기본 감소 동작을 막는다. */
+    onStepperDecrementClick?: (event: React.MouseEvent<HTMLButtonElement>, value: number | null) => void;
+    /** 증가 버튼 클릭 이벤트. `event.preventDefault()` 호출 시 기본 증가 동작을 막는다. */
+    onStepperIncrementClick?: (event: React.MouseEvent<HTMLButtonElement>, value: number | null) => void;
+    /**
+     * 길게 누를 때 반복 간격이 점점 짧아지는 가속 효과.
+     * @default true
+     */
+    stepperAccelerate?: boolean;
+    /**
+     * 길게 누른 뒤, 숫자가 **한 번** 바뀐 다음 자동 반복이 시작되기까지의 대기 시간(ms).
+     * @default 300
+     */
+    stepperAccelerateHoldDelay?: number;
+    /**
+     * 자동 반복이 시작된 뒤, 시작 속도에서 최고 속도까지 빨라지는 데 걸리는 시간(ms).
+     * @default 1800
+     */
+    stepperAccelerateRampDuration?: number;
+    /**
+     * 길게 눌렀을 때 **처음** 자동으로 숫자가 바뀌는 속도
+     * 예) `5` → 1초에 5번(약 0.2초마다 1씩 증가)
+     * @default 5
+     */
+    stepperAccelerateCps?: number;
+    /**
+     * 가속이 끝난 뒤 유지되는 **최고** 속도.
+     * 예) `100` → 1초에 100번 반복 (약 0.01초마다 1씩 증가)
+     * @default 100
+     */
+    stepperAccelerateMaxCps?: number;
+};
+export default function NumberStepper(props: NumberStepperProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/index.d.ts

@@ -3,5 +3,8 @@ export type { GroupedInputWrapperProps } from "./GroupedInputWrapper";
 export { ColonBox } from "./ColonBox";
 export type { ColonBoxProps } from "./ColonBox";
 export { default as NumberField } from "./NumberField";
-export type { NumberFieldProps } from "./NumberField";
+export type { NumberFieldProps, NumberFieldAlign } from "./NumberField";
+export { default as NumberStepper } from "./NumberStepper";
+export type { NumberStepperProps } from "./NumberStepper";
 export { default as NumberSpinner } from "./NumberSpinner";
+export type { NumberSpinnerProps } from "./NumberSpinner";

package/dist/components/numberBasic.d.ts

@@ -0,0 +1,72 @@
+/**
+ * numberBasic.tsx
+ *
+ * NumberField · NumberStepper · NumberSpinner 공용 타입/헬퍼/폼 바인딩.
+ * 값 상태·clamp·grouping 등 동작 로직은 `useNumberBasic` 훅이 담당하고,
+ * 이 파일은 세 컴포넌트가 공유하는 순수 헬퍼와 타입만 모은다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import * as React from "react";
+import { NumberField as BaseNumberField } from "@base-ui/react/number-field";
+import type { NumberFieldRoot } from "@base-ui/react/number-field";
+import type { FormLike } from "../types";
+import type { ThousandSeparatorProp } from "../utils/number";
+export type NumberFieldAlign = "left" | "center" | "right";
+/**
+ * 세 숫자 컴포넌트(NumberField·NumberStepper·NumberSpinner) 공통 props.
+ * 각 컴포넌트는 여기에 자기만의 표시 옵션을 더한다.
+ */
+export type NumberBaseProps = BaseNumberField.Root.Props & {
+    label?: React.ReactNode;
+    size?: "small" | "medium";
+    error?: boolean;
+    fullWidth?: boolean;
+    form?: FormLike | null;
+    suffix?: React.ReactNode;
+    /** 입력 숫자 텍스트 정렬 방향. */
+    align?: NumberFieldAlign;
+    /**
+     * 천 단위 구분.
+     * - `false`: 구분 없음
+     * - `true` / `undefined`(기본): `Intl` 로케일 규칙 (`locale`·`format`과 함께)
+     * - `string`: 구분 문자 직접 지정 (예: `","`, `"."`, `" "`)
+     * @default true
+     */
+    thousandSeparator?: ThousandSeparatorProp;
+    /**
+     * 값이 정확히 0일 때 입력칸을 빈칸으로 표시한다 (placeholder만 노출).
+     *
+     * 내부 값은 항상 숫자(0 포함)로 유지되므로 base-ui의 스피너 증감이 정상 동작한다.
+     * 표시(렌더링)만 비우며, `onValueChange`로는 숫자 0이 그대로 전달된다.
+     * 0을 빈칸으로 표시하려면 `clearWhenZero={true}`로 켠다.
+     * @default false
+     */
+    clearWhenZero?: boolean;
+};
+/** 다양한 입력(문자열·null 포함)을 NumberField 내부 숫자 값으로 정규화 */
+export declare function normalizeNumberFieldValue(value: unknown): number | null;
+/** default OutlinedInput과 동일한 입력 영역 높이 */
+export declare function getNumberFieldControlHeight(size: "small" | "medium"): 40 | 56;
+/**
+ * FormControl이 SSR에서 shrink label 상태를 올바르게 잡도록 하는 placeholder.
+ */
+export declare function SSRInitialFilled(_: BaseNumberField.Root.Props): null;
+export declare namespace SSRInitialFilled {
+    var muiName: string;
+}
+/**
+ * `form`/`name`이 주어졌을 때 폼 값과 양방향으로 연결한다.
+ * form이 있는 경우에만 렌더되는 하위 컴포넌트에서 무조건 호출되어야 한다
+ * (조건부 호출 금지). NumberField·NumberStepper·NumberSpinner 공통.
+ */
+export declare function useNumberFormBinding({ form, name, onValueChange, }: {
+    form: FormLike;
+    name: string;
+    onValueChange?: (value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void;
+}): {
+    value: number | null;
+    onValueChange: (next: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void;
+};

package/dist/hooks/useNumberBasic.d.ts

@@ -0,0 +1,52 @@
+/**
+ * useNumberBasic.ts
+ *
+ * NumberField · NumberStepper · NumberSpinner 공용 동작 훅.
+ * 값 상태(controlled/uncontrolled) · min/max 즉시 clamp · 천 단위 live grouping ·
+ * format 정규화 · Base UI Root 배선에 필요한 값들을 한곳에서 만들어 돌려준다.
+ * 각 컴포넌트는 이 훅을 호출하고 "가운데 표시/입력 UI"만 다르게 렌더한다.
+ *
+ * clamp는 min/max가 주어졌을 때만, 폼 연동은 form이 주어졌을 때만 동작하므로
+ * 세 컴포넌트에 동일하게 적용해도 순수한 상위호환이다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import * as React from "react";
+import type { NumberFieldRoot } from "@base-ui/react/number-field";
+import { type ThousandSeparatorProp } from "../utils/number";
+export interface UseNumberBasicParams {
+    value?: number | null;
+    defaultValue?: number | string | null;
+    onValueChange?: (value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void;
+    min?: number;
+    max?: number;
+    locale?: Intl.LocalesArgument;
+    format?: Intl.NumberFormatOptions;
+    thousandSeparator?: ThousandSeparatorProp;
+    clearWhenZero?: boolean;
+    /**
+     * 초기값(defaultValue)이 없을 때 min(또는 0)으로 채울지 여부.
+     * 스테퍼처럼 항상 숫자 값이 있어야 증감이 자연스러운 경우 true.
+     * @default false
+     */
+    initialFallbackToMin?: boolean;
+}
+export declare function useNumberBasic({ value, defaultValue, onValueChange, min, max, locale, format, thousandSeparator, clearWhenZero, initialFallbackToMin, }: UseNumberBasicParams): {
+    isControlled: boolean;
+    resolvedValue: number | null;
+    setInternalValue: React.Dispatch<React.SetStateAction<number | null>>;
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    liveGrouping: {
+        getDisplayValue: (baseInputValue: string) => string;
+        syncBaseInputValue: (baseInputValue: string) => void;
+        setLiveDisplay: (text: string | null) => void;
+        wrapOnChange: (handler: React.ChangeEventHandler<HTMLInputElement> | undefined) => (event: React.ChangeEvent<HTMLInputElement>) => void;
+        wrapOnBlur: (handler: React.FocusEventHandler<HTMLInputElement> | undefined) => (event: React.FocusEvent<HTMLInputElement, Element>) => void;
+        wrapOnFocus: (handler: React.FocusEventHandler<HTMLInputElement> | undefined) => (event: React.FocusEvent<HTMLInputElement, Element>) => void;
+    };
+    groupingEnabled: boolean;
+    handleValueChange: (next: number | null, details: NumberFieldRoot.ChangeEventDetails) => void;
+    formatForRoot: Intl.NumberFormatOptions | undefined;
+};

package/dist/index.d.ts

@@ -21,8 +21,8 @@ export { ButtonGroup } from "./ButtonGroup";
 export { DateRange } from "./DateRange";
 export { Slider } from "./Slider";
 export { Stepper } from "./Stepper";
-export { NumberField, NumberSpinner } from "./NumberField";
-export type { NumberFieldProps, NumberFieldVariant } from "./NumberField";
+export { NumberField, NumberStepper, NumberSpinner } from "./NumberField";
+export type { NumberFieldProps, NumberFieldAlign, NumberStepperProps, NumberSpinnerProps, } from "./NumberField";
 export { Autocomplete } from "./Autocomplete";
 export { Select } from "./Select";
 export { LabelSelect } from "./LabelSelect";