@ehfuse/mui-form-controls 3.1.62 → 3.2.1

package/dist/components/ReadonlyDisplay.d.ts

@@ -1,14 +1,21 @@
 /**
  * ReadonlyDisplay.tsx
  *
- * readonly 입력칸을 "실제 <input> 없이" 그리는 경량 표시 컴포넌트.
+ * readonly / disabled 입력칸을 "실제 <input> 없이" 그리는 표시 컴포넌트.
  *
- * 배경: readonly 필드도 기본은 MUI TextField(내부 input + IME/상태 훅 + 인스턴스별 sx)를 렌더한다.
- * 상품 목록처럼 readonly 필드가 수백 개면 이 입력 머신러리 비용이 커서 화면이 느려진다.
- * `readonlyLight` prop 을 켜면 이 컴포넌트로 대체돼, outlined 입력칸과 동일한 외관(노치 라벨 + 테두리)을
- * fieldset/legend 로 재현하되 실제 입력 요소를 만들지 않아 렌더 비용이 크게 낮아진다.
+ * mfc 의 readonly / disabled 는 기본적으로 이 컴포넌트로 렌더된다.
+ * - readonly : 조작 불가 + 글자색은 편집 가능할 때와 동일(흐려지지 않음).
+ * - disabled : 조작 불가 + 글자/라벨/테두리가 흐려짐(`dimmed`).
  *
- * 외관은 MUI OutlinedInput 마크업(fieldset+legend)을 그대로 따르므로 테마의 기본 테두리/반경/색을 물려받는다.
+ * 외관은 MUI OutlinedInput 마크업(fieldset+legend)을 그대로 따르므로 테마의 기본 테두리/반경/색을 물려받고,
+ * 실제 입력 요소/IME/포커스 머신러리가 없어 렌더 비용이 크게 낮다.
+ * 실제 <input> 이 꼭 필요하면 소비처가 `readonlyInput` prop 으로 예전 동작(진짜 입력칸)을 되살릴 수 있다.
+ *
+ * ⚠️ 클래스 호환: 소비처 `sx` 에는 `& .MuiInputBase-input { textAlign }`, `& .MuiOutlinedInput-root { minHeight }`
+ * 같은 MUI 내부 셀렉터가 흔하다. 박스 렌더로 바뀌어도 그 스타일이 죽지 않도록 각 파트에 MUI 와 동일한
+ * 클래스명(MuiInputBase-root / MuiOutlinedInput-root / MuiInputBase-input / MuiOutlinedInput-input /
+ * MuiOutlinedInput-notchedOutline / MuiInputLabel-root / Mui-disabled)을 그대로 붙이고,
+ * 값 텍스트가 MUI input 과 같은 패딩을 갖게 해서 패딩/정렬 override 도 동일하게 먹도록 맞춘다.
  *
  * @license MIT
  * @copyright 2025 김영진 (Kim Young Jin)
@@ -22,13 +29,28 @@ export interface ReadonlyDisplayProps {
     value?: React.ReactNode;
     prefix?: React.ReactNode;
     suffix?: React.ReactNode;
+    /** 값 왼쪽 adornment(입력칸의 startAdornment 자리). */
+    startAdornment?: React.ReactNode;
+    /** 값 오른쪽 adornment(입력칸의 endAdornment 자리 — 복사 버튼 등 클릭 가능한 요소도 가능). */
+    endAdornment?: React.ReactNode;
     /** suffix/prefix 를 값이 있을 때만 표시할지 여부. */
     showAffixOnlyWithValue?: boolean;
     align?: "left" | "right" | "center";
     size?: "small" | "medium";
     fullWidth?: boolean;
+    /** true 면 disabled 입력처럼 글자/라벨/테두리를 흐리게 그린다. */
+    dimmed?: boolean;
+    /** true 면 값의 줄바꿈을 보존하고 여러 줄로 표시한다(말줄임 대신). */
+    multiline?: boolean;
+    /** multiline 일 때 최소 줄 수(입력칸의 minRows 와 같은 높이를 유지한다). */
+    minRows?: number;
+    /** 값 표시 영역 클릭 핸들러(읽기 전용 칸을 눌러 다이얼로그를 여는 패턴 지원). */
+    onClick?: React.MouseEventHandler<HTMLDivElement>;
+    /** 네이티브 툴팁. */
+    title?: string;
     className?: string;
+    id?: string;
     sx?: SxProps<Theme>;
 }
-/** readonly 입력칸을 실제 input 없이 그리는 경량 표시 컴포넌트. */
-export declare function ReadonlyDisplay({ label, value, prefix, suffix, showAffixOnlyWithValue, align, size, fullWidth, className, sx, }: ReadonlyDisplayProps): import("react/jsx-runtime").JSX.Element;
+/** readonly/disabled 입력칸을 실제 input 없이 그리는 표시 컴포넌트. */
+export declare function ReadonlyDisplay({ label, value, prefix, suffix, startAdornment, endAdornment, showAffixOnlyWithValue, align, size, fullWidth, dimmed, multiline, minRows, onClick, title, className, id, sx, }: ReadonlyDisplayProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ReadonlyField.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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;
+/**
+ * slotProps 에서 박스 렌더가 살릴 수 있는 것만 뽑는다.
+ * - `input.start/endAdornment` : 박스에도 그대로 붙인다(복사 버튼 등 클릭 가능한 요소 포함).
+ * - `htmlInput.style.textAlign` : 값 정렬로 옮긴다.
+ * 함수형 slotProps 는 ownerState 가 없어 해석할 수 없으므로 무시한다.
+ */
+export declare function pickSlotPropsForBox(slotProps: unknown): {
+    startAdornment?: React.ReactNode;
+    endAdornment?: React.ReactNode;
+    align?: "left" | "right" | "center";
+};
+/** 컨트롤 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"];
+    slotProps?: unknown;
+    multiline?: boolean;
+    minRows?: number | string;
+    /** Select/LabelSelect 는 바깥 FormControl 에 레이아웃 sx 를 받는다 — 박스에도 함께 적용한다. */
+    formControlProps?: {
+        sx?: ReadonlyDisplayProps["sx"];
+    };
+}): {
+    startAdornment?: React.ReactNode;
+    endAdornment?: React.ReactNode;
+    align?: "left" | "right" | "center";
+    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>;
+    multiline: boolean;
+    minRows: number | undefined;
+    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";