@ehfuse/mui-form-controls 3.1.62 → 3.2.0

package/dist/components/ReadonlyField.d.ts

@@ -0,0 +1,77 @@
+/**
+ * ReadonlyField.tsx
+ *
+ * mfc 컨트롤들이 readonly / disabled 상태에서 공통으로 쓰는 "박스 표시" 진입점.
+ *
+ * 설계 규칙 (v3.2.0 부터):
+ * - `readonly`  : 실제 <input> 대신 {@link ReadonlyDisplay} 박스로 렌더. 글자색은 편집 상태와 동일(흐려지지 않음).
+ * - `disabled`  : 같은 박스로 렌더하되 글자/라벨/테두리를 흐리게(dimmed) 그린다. 즉 disabled = readonly + 흐림.
+ * - `readonlyInput` : 예전처럼 진짜 입력칸을 렌더한다(포커스/선택/커스텀 adornment 가 꼭 필요한 칸의 탈출구).
+ * - `readonlyLight` : v3.2.0 에서 기본 동작이 되었으므로 무시된다(@deprecated).
+ *
+ * 훅 개수 안정성: 박스 분기는 **훅을 가진 Base 컴포넌트 바깥(export 래퍼)** 에서 한다.
+ * Base 안에서 early-return 하면 readonly/disabled 플래그가 런타임에 뒤집힐 때 훅 개수가 달라져 React 가 죽는다.
+ * 서로 다른 컴포넌트 타입으로 갈라지면 React 가 언마운트/마운트로 처리해 안전하다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import React from "react";
+import type { ReadonlyDisplayProps } from "./ReadonlyDisplay";
+import type { FormLike } from "../types";
+/** readonly/disabled 판정에 필요한 최소 props. */
+export type ReadonlyBoxFlags = {
+    readonly?: boolean;
+    disabled?: boolean;
+    /** true 면 readonly/disabled 여도 진짜 입력칸을 렌더한다. */
+    readonlyInput?: boolean;
+};
+/**
+ * 이 컨트롤을 박스(ReadonlyDisplay)로 그려야 하는지.
+ * readonly 든 disabled 든 "편집 불가" 이므로 둘 다 박스로 간다. 차이는 흐림(dimmed) 뿐이다.
+ */
+export declare function shouldRenderReadonlyBox(props: ReadonlyBoxFlags): boolean;
+/** 컨트롤 props 에서 박스 렌더에 필요한 공통 필드만 뽑는다(컴포넌트마다 반복되는 보일러플레이트 제거). */
+export declare function commonReadonlyBoxProps(props: {
+    form?: FormLike | null;
+    name?: string;
+    value?: unknown;
+    label?: React.ReactNode;
+    disabled?: boolean;
+    size?: "small" | "medium" | string;
+    fullWidth?: boolean;
+    className?: string;
+    id?: string;
+    onClick?: unknown;
+    sx?: ReadonlyDisplayProps["sx"];
+}): {
+    form: FormLike | null | undefined;
+    name: string | undefined;
+    value: unknown;
+    label: React.ReactNode;
+    disabled: boolean | undefined;
+    size: "small" | "medium";
+    fullWidth: boolean | undefined;
+    className: string | undefined;
+    id: string | undefined;
+    onClick: React.MouseEventHandler<HTMLDivElement>;
+    sx: import("@mui/system").SxProps<import("@mui/material").Theme> | undefined;
+};
+type ReadonlyFieldProps = Omit<ReadonlyDisplayProps, "value" | "dimmed"> & {
+    /** form 이 있으면 name 으로 값을 구독한다. */
+    form?: FormLike | null;
+    name?: string;
+    /** form 이 없을 때 쓸 값. */
+    value?: unknown;
+    /** 원시 값을 표시 문자열로 바꾸는 함수(포맷 마스크 등). */
+    format?: (value: unknown) => React.ReactNode;
+    /** disabled 면 true — 흐리게 그린다. */
+    disabled?: boolean;
+};
+/**
+ * readonly/disabled 컨트롤의 공통 박스 렌더.
+ * form 유무로 컴포넌트 타입이 갈리므로 훅 개수는 각 타입 안에서 고정된다.
+ */
+export declare function ReadonlyField(props: ReadonlyFieldProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/index.d.ts

@@ -42,5 +42,6 @@ export { CardNumTextField } from "./CardNumTextField";
 export { useKoreanHolidays, useKoreanHolidaysRange } from "./hooks";
 export { ReadonlyDisplay } from "./components/ReadonlyDisplay";
 export type { ReadonlyDisplayProps } from "./components/ReadonlyDisplay";
+export { ReadonlyField, shouldRenderReadonlyBox, } from "./components/ReadonlyField";
 export { CardIcon, VisaIcon, MastercardIcon, AmexIcon, JcbIcon, DinersIcon, DiscoverIcon, UnionPayIcon, BcIcon, } from "./icons";
 export type { SearchTextFieldProps, ClearTextFieldProps, TagsTextFieldProps, PasswordTextFieldProps, TextFieldProps, TextAreaProps, CheckboxProps, SwitchProps, RadioGroupProps, RadioOption, DateRangeProps, SliderProps, RatingProps, ToggleButtonProps, ToggleButtonGroupProps, ToggleButtonGroupOption, ButtonGroupProps, StepperProps, AutocompleteProps, AutocompleteOption, SelectProps, SelectOption, LabelSelectProps, LabelSelectOption, AddressTextFieldProps, DaumPostcodeData, PasswordValidationRules, PasswordValidationResult, PhoneTextFieldProps, PhoneFormat, NumberTextFieldProps, JuminTextFieldProps, JuminInfo, VerificationCodeTextFieldProps, VerificationCodeType, EmailTextFieldProps, CustomDomain, DateTextFieldProps, DateFormat, TimeTextFieldProps, TimeFormat, DateTimeTextFieldProps, DateTimeFormat, BizNumTextFieldProps, CorpNumTextFieldProps, CardNumTextFieldProps, CardNumTextFieldHandle, SelectChangeEvent, } from "./types";