@ehfuse/mui-form-controls 3.1.62 → 3.2.0

package/dist/types.d.ts

@@ -40,14 +40,25 @@ export type FormLike = {
     setFormValue?: (name: string, value: unknown) => void;
 };
 export type BaseTextFieldProps = {
+    /**
+     * 읽기 전용 모드 (기본값: false).
+     * 값 변경/포커스 등 상호작용만 막고 **외관은 편집 가능한 상태 그대로** 둔다(글자·라벨이 흐려지지 않는다).
+     * 값을 "보여주는 것"이 목적일 때 쓴다.
+     * 반대로 `disabled` 는 readonly 와 동일하게 상호작용을 막으면서 **글자까지 흐리게** 표시한다
+     * ("지금은 쓸 수 없는 칸"을 알릴 때). 두 prop 을 동시에 주면 disabled 가 이긴다.
+     */
     readonly?: boolean;
     /**
-     * readonly 일 때 실제 <input> 대신 경량 표시(ReadonlyDisplay)로 렌더할지 여부 (기본값: false).
-     * 상품 목록처럼 readonly 필드가 많아 입력 머신러리 렌더 비용이 부담될 때 켠다.
-     * 외관은 outlined 입력칸과 동일하되 입력 요소/포커스/IME 처리가 없어 가볍다.
-     * readonly 가 false 면 무시된다.
+     * @deprecated v3.2.0 부터 readonly/disabled 는 **항상** 경량 박스(ReadonlyDisplay)로 렌더되므로 이 prop 은 무시된다.
+     * 예전처럼 진짜 <input> 이 필요하면 `readonlyInput` 을 쓴다.
      */
     readonlyLight?: boolean;
+    /**
+     * readonly/disabled 여도 경량 박스 대신 **진짜 입력 컴포넌트**로 렌더할지 여부 (기본값: false).
+     * 박스 렌더는 입력 요소가 없어 포커스/텍스트 커서/커스텀 slotProps 가 동작하지 않으므로,
+     * 그런 게 꼭 필요한 칸(외부에서 inputRef 로 focus/select 하거나, MuiInputBase 셀렉터로 스타일링하는 칸)의 탈출구다.
+     */
+    readonlyInput?: boolean;
     debounce?: number;
     form?: FormLike | null;
     disableInternalState?: boolean;

package/dist/utils/index.d.ts

@@ -17,3 +17,4 @@ export { validateBusinessNumber, validateCorpNumber } from "./biznum";
 export { validateCardNumber, detectCardBrand } from "./card";
 export type { CardBrand } from "./card";
 export { REGION_MAP, extractJuminInfo, validateJuminChecksum, validateJuminBirthDate, isJuminValueValid, isJuminValueInvalidState, sanitizeJuminFrontBirthDigits, canAppendJuminBirthDigit, maxDayForJuminFrontYyMm, } from "./jumin";
+export { isInteractionLocked, interactionLockSx, withInteractionLockSx, interactionLockInputProps, } from "./readonly";

package/dist/utils/readonly.d.ts

@@ -0,0 +1,34 @@
+/**
+ * utils/readonly.ts
+ *
+ * readonly 와 disabled 의 동작을 분리하기 위한 공통 헬퍼.
+ *
+ * - `readonly`: 상호작용(클릭/키보드/값 변경)만 차단하고 **외관은 그대로** 둔다. 글자가 흐려지지 않는다.
+ * - `disabled`: MUI 기본 동작(상호작용 차단 + 글자 흐림)을 그대로 쓴다. readonly 를 포함하는 상위 상태다.
+ *
+ * MUI 의 Checkbox/Switch/Radio/Slider/ToggleButton 처럼 `readOnly` 개념이 없는 컨트롤은
+ * 예전엔 readonly 를 `disabled` 로 매핑해 흐려졌다. 이제는 아래 헬퍼로
+ * "포인터/키보드 차단 + onChange 무시" 만 적용하고 색은 건드리지 않는다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import type React from "react";
+import type { SxProps, Theme } from "@mui/material/styles";
+/** readonly 이면서 disabled 는 아닌, "흐리지 않게 차단만" 해야 하는 상태인지. */
+export declare function isInteractionLocked(readonly?: boolean, disabled?: boolean): boolean;
+/** 상호작용 차단용 sx (외관에는 영향 없음). */
+export declare const interactionLockSx: {
+    readonly pointerEvents: "none";
+};
+/**
+ * 호출부 sx 앞에 상호작용 차단 sx 를 끼워 배열 형태로 합친다.
+ * (MUI sx 배열은 뒤 항목이 이기므로 호출부 지정이 항상 우선한다.)
+ */
+export declare function withInteractionLockSx(locked: boolean, sx?: SxProps<Theme>): SxProps<Theme>;
+/**
+ * 상호작용 차단 시 포커스 링/탭 이동까지 막기 위한 input 속성.
+ * pointerEvents 만으로는 Tab + Space 키 조작이 남는다.
+ */
+export declare function interactionLockInputProps<T extends React.InputHTMLAttributes<HTMLInputElement>>(locked: boolean, inputProps?: T): T | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ehfuse/mui-form-controls",
-    "version": "3.1.62",
+    "version": "3.2.0",
     "description": "Material-UI form controls and text fields for complex forms",
     "private": false,
     "publishConfig": {

package/dist/SwitchField.d.ts

@@ -1,10 +0,0 @@
-/**
- * SwitchField.tsx
- *
- * @license MIT
- * @copyright 2025 김영진 (Kim Young Jin)
- * @author 김영진 (ehfuse@gmail.com)
- */
-import React from "react";
-import type { SwitchFieldProps } from "./types";
-export declare const SwitchField: React.ForwardRefExoticComponent<Omit<SwitchFieldProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;

package/dist/ToggleButtonGroupField.d.ts

@@ -1,10 +0,0 @@
-/**
- * ToggleButtonGroupField.tsx
- *
- * @license MIT
- * @copyright 2025 김영진 (Kim Young Jin)
- * @author 김영진 (ehfuse@gmail.com)
- */
-import React from "react";
-import type { ToggleButtonGroupFieldProps } from "./types";
-export declare const ToggleButtonGroupField: React.ForwardRefExoticComponent<Omit<ToggleButtonGroupFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/devDebug.d.ts

@@ -1,35 +0,0 @@
-/**
- * 패키지 전역 개발용 콘솔 로그 스위치.
- * 앱 진입 시 `setMuiFormControlsDebug(true)` 한 번이면
- * DateTextField / TimeTextField / DateTimeTextField 등에서 value 동기화 로그가 출력된다.
- * 필드가 많으면 `nameIncludes` / `nameMatch`, 컴포넌트만 골라서는 `scopes`로 범위를 줄일 수 있다.
- *
- * @license MIT
- */
-/** value 동기화 로그를 낼 수 있는 컴포넌트 scope (muiFormControlsDevLog 첫 인자와 동일) */
-export type MuiFormControlsDebugScope = "DateTextField" | "TimeTextField" | "DateTimeTextField";
-export type MuiFormControlsDebugOptions = {
-    /** `name` prop에 이 부분 문자열이 있을 때만 로그 (여러 필드일 때 노이즈 감소) */
-    nameIncludes?: string;
-    /** `name` prop이 이 정규식과 맞을 때만 로그 */
-    nameMatch?: RegExp;
-    /**
-     * 한 개 이상이면 **이 컴포넌트(scope)에서만** 로그.
-     * 생략 또는 빈 배열이면 scope 제한 없음(이름 필터만 적용).
-     */
-    scopes?: MuiFormControlsDebugScope[];
-};
-/**
- * @param enabled 로그 출력 여부
- * @param options `scopes` / `nameIncludes` / `nameMatch`로 범위 축소 (조건은 AND)
- */
-export declare function setMuiFormControlsDebug(enabled: boolean, options?: MuiFormControlsDebugOptions): void;
-export declare function getMuiFormControlsDebug(): boolean;
-export declare function getMuiFormControlsDebugOptions(): Readonly<MuiFormControlsDebugOptions & {
-    enabled: boolean;
-}>;
-/**
- * 컴포넌트 내부 전용.
- * @param scope 예: "DateTextField"
- */
-export declare function muiFormControlsDevLog(scope: string, payload: Record<string, unknown>): void;

package/dist/utils/outlinedFieldStyles.d.ts

@@ -1,5 +0,0 @@
-import type { SxProps, Theme } from "@mui/material/styles";
-export declare const CLOSED_OUTLINED_BORDER_COLOR = "rgba(0, 0, 0, 0.23)";
-export declare const CLOSED_OUTLINED_LABEL_COLOR = "rgba(0, 0, 0, 0.6)";
-export declare const outlinedFieldFocusToneSx: SxProps<Theme>;
-export declare const outlinedFieldReadonlyToneSx: SxProps<Theme>;