@ehfuse/mui-form-controls 3.4.5 → 3.5.0

package/dist/property/PropertyAddress.d.ts

@@ -0,0 +1,32 @@
+/**
+ * property/PropertyAddress.tsx
+ *
+ * 주소 값 — 그대로 고쳐 적거나, 돋보기로 우편번호 검색(Daum)을 열어 고른다(고르면 바로 저장).
+ * 검색 창은 react-daum-postcode 다 — 이 패키지 번들에 함께 묶인다(작다 — 검색 화면 자체는 Daum 스크립트를 열 때 받는다).
+ * 메인 진입점에서 내보낸다 — address 진입점은 따로 묶여 앱 기본값(FormControlsConfig) 문맥을 같이 쓰지 못한다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import { type ReactNode } from "react";
+import type { SxProps, Theme } from "@mui/material";
+import { type PropertyInputProps } from "./PropertyText";
+import { type PropertyRowLayoutProps } from "./PropertyRow";
+import { type PropertyBindingProps } from "./binding";
+export interface PropertyAddressInputProps extends PropertyBindingProps<string>, Pick<PropertyInputProps, "placeholder" | "readOnly" | "appearance" | "sx"> {
+    /** 글자 수 한도. 기본 200. */
+    maxLength?: number;
+}
+/** 주소 칸(줄 없이 칸 + 검색 단추). `form` + `name` 또는 `value` + `onCommit`. */
+export declare const PropertyAddressInput: {
+    (props: PropertyAddressInputProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export interface PropertyAddressProps extends PropertyAddressInputProps, Omit<PropertyRowLayoutProps, "sx" | "appearance"> {
+    icon?: ReactNode;
+    label: ReactNode;
+    rowSx?: SxProps<Theme>;
+}
+/** 주소 속성 줄. */
+export declare function PropertyAddress({ icon, label, wide, full, rowStart, alignTop, rowSx, appearance, ...input }: PropertyAddressProps): import("react/jsx-runtime").JSX.Element;

package/dist/property/PropertyRow.d.ts

@@ -0,0 +1,65 @@
+/**
+ * property/PropertyRow.tsx
+ *
+ * 속성 한 줄 — "아이콘 + 라벨 | 값". 값을 누르면 그 자리에서 고친다(노션풍 상세).
+ * 묶음(PropertyGrid)은 화면 폭이 아니라 **묶음의 폭**으로 1 · 2 · 4열을 가른다(컨테이너 쿼리) —
+ * 같은 상세가 드로어 · 가로분할의 반쪽 · 세로분할의 넓은 패널에 서기 때문이다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import type { SxProps, Theme } from "@mui/material";
+import type { ReactNode } from "react";
+import { type PropertyAppearance } from "./appearance";
+/** 2열이 되는 묶음 폭 — 줄 하나(라벨 132 + 값)가 270px 남짓은 남아야 값이 잘리지 않는다. */
+export declare const PROPERTY_GRID_TWO_COLUMN_MIN = 560;
+/** 4열이 되는 묶음 폭 — 분할 화면의 넓은 아래 패널. */
+export declare const PROPERTY_GRID_FOUR_COLUMN_MIN = 1180;
+/** 4열 컨테이너 쿼리 — 묶음 밖에서 줄 자리를 4열에 맞출 때 쓴다(sx 키). */
+export declare const PROPERTY_GRID_FOUR_CQ = "@container (min-width: 1180px)";
+/** 줄 자리(묶음 안에서 몇 칸을 쓰나) — 값 칸 부품들이 함께 받는다. */
+export interface PropertyRowLayoutProps {
+    /** 긴 값 — 1·2열에서는 한 줄을 다 쓰고, 4열에서는 두 칸을 쓴다(주소 · 상세주소가 한 줄에 나란히 선다). */
+    wide?: boolean;
+    /** 몇 열이든 한 줄을 다 쓴다(메모 · 비고처럼 여러 줄 글). */
+    full?: boolean;
+    /** 4열에서 새 줄의 첫 칸부터 선다(wide 와 함께). */
+    rowStart?: boolean;
+    /** 값이 여러 줄이면 라벨을 위에 붙인다. */
+    alignTop?: boolean;
+    /** 줄 루트에 더할 스타일(격자 order · gridColumn 등). */
+    sx?: SxProps<Theme>;
+    /** 이 줄만의 모양 값(앱 기본값 위에 얹는다). */
+    appearance?: PropertyAppearance;
+}
+export interface PropertyRowProps extends PropertyRowLayoutProps {
+    icon?: ReactNode;
+    label: ReactNode;
+    /** 값 영역을 눌렀다(고르기 메뉴 · 팝퍼를 여는 줄) — 없으면 값 영역 안의 칸이 스스로 입력을 받는다. */
+    onClick?: (anchor: HTMLElement) => void;
+    /** 값 영역에 더할 스타일. */
+    valueSx?: SxProps<Theme>;
+    children?: ReactNode;
+}
+/** 속성 한 줄 — 아이콘 + 라벨 | 값. */
+export declare function PropertyRow({ icon, label, onClick, alignTop, wide, full, rowStart, sx, valueSx, appearance, children }: PropertyRowProps): import("react/jsx-runtime").JSX.Element;
+export interface PropertyGridProps {
+    children?: ReactNode;
+    /** 2열이 되는 묶음 폭(px). 기본 560. */
+    twoColumnMin?: number;
+    /** 4열이 되는 묶음 폭(px). 기본 1180. */
+    fourColumnMin?: number;
+    /** 격자에 더할 스타일. */
+    sx?: SxProps<Theme>;
+}
+/**
+ * 속성 줄 묶음 — 묶음 폭에 따라 1 · 2 · 4열이다. 줄은 왼쪽→오른쪽, 위→아래 순서로 찬다.
+ * 한 줄을 다 써야 하는 줄은 wide · full 을 준다.
+ */
+export declare function PropertyGrid({ children, twoColumnMin, fourColumnMin, sx }: PropertyGridProps): import("react/jsx-runtime").JSX.Element;
+/** 비어 있는 값 — 옅은 "비어 있음". */
+export declare function PropertyEmpty({ text, appearance }: {
+    text?: ReactNode;
+    appearance?: PropertyAppearance;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/property/PropertySelect.d.ts

@@ -0,0 +1,71 @@
+/**
+ * property/PropertySelect.tsx
+ *
+ * 고르는 값의 줄 — 값을 누르면 그 아래에 메뉴가 바로 뜬다(펼침 애니메이션 없음 — 누른 자리에서 늦게 따라오는 것처럼 보인다).
+ * onCreate 를 주면 메뉴 맨 위에 찾기 칸을 두고, 없는 말을 치면 그 말로 새 항목을 만든다(노션처럼).
+ * 여러 개 고르기(PropertyMultiSelect)는 메뉴에서 눌러 켜고 끄고, 메뉴를 닫을 때 한 번 저장한다.
+ * 켜고 끄기(PropertySwitch)는 누르는 즉시 저장한다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import { type ReactNode } from "react";
+import { type PropertyRowLayoutProps } from "./PropertyRow";
+import { type PropertyBindingProps } from "./binding";
+/** 고르기 메뉴의 한 칸. */
+export interface PropertyOption {
+    value: string | number;
+    label: string;
+}
+/** 속성 줄 머리(아이콘 · 라벨 · 자리). */
+interface PropertyHeadProps extends PropertyRowLayoutProps {
+    icon?: ReactNode;
+    label: ReactNode;
+    readOnly?: boolean;
+}
+export type PropertySelectValue = string | number | "";
+export interface PropertySelectProps extends PropertyHeadProps, PropertyBindingProps<PropertySelectValue> {
+    options: PropertyOption[];
+    /** 비움 칸의 글 — 없으면 비우는 칸을 두지 않는다(꼭 하나는 골라야 하는 값). 빈 값의 표시 글도 이것이다. */
+    emptyLabel?: string;
+    /** 고른 값(onCommit 과 같은 때 — 예전 이름). */
+    onChange?: (next: PropertySelectValue) => void;
+    /** 메뉴 맨 아래의 덧붙임(예: "분류 관리…"). */
+    footer?: ReactNode;
+    /** 값 · 메뉴 줄을 글 대신 그린다(색 칩). */
+    renderLabel?: (option: PropertyOption) => ReactNode;
+    /** 주면 메뉴 맨 위에 찾기 칸을 두고, 없는 말을 치면 그 말로 새 항목을 만든다. true 면 만든 말을 고른다. */
+    onCreate?: (text: string) => Promise<boolean> | boolean;
+}
+/** 고르는 값의 줄. `form` + `name` 또는 `value` + `onCommit`(onChange). */
+export declare const PropertySelect: {
+    (props: PropertySelectProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export interface PropertyMultiSelectProps extends PropertyHeadProps, PropertyBindingProps<string[]> {
+    options: string[];
+    /** 고른 목록(onCommit 과 같은 때 — 예전 이름). */
+    onChange?: (next: string[]) => void;
+    /** 값 · 메뉴 줄을 글 대신 그린다(색 칩). */
+    renderLabel?: (option: string) => ReactNode;
+    /** 찾기 칸 + 쳐서 새 항목(PropertySelect 와 같다). true 면 만든 말을 켠다. */
+    onCreate?: (text: string) => Promise<boolean> | boolean;
+}
+/** 여러 개 고르는 값의 줄. `form` + `name` 또는 `value` + `onCommit`(onChange). */
+export declare const PropertyMultiSelect: {
+    (props: PropertyMultiSelectProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export interface PropertySwitchProps extends PropertyHeadProps, PropertyBindingProps<boolean> {
+    /** 켜짐(value 와 같다 — 예전 이름). */
+    checked?: boolean;
+    /** 바뀐 값(onCommit 과 같은 때 — 예전 이름). */
+    onChange?: (next: boolean) => void;
+}
+/** 켜고 끄는 값의 줄 — 누르는 즉시 저장한다. `form` + `name` 또는 `checked`(value) + `onCommit`(onChange). */
+export declare const PropertySwitch: {
+    (props: PropertySwitchProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export {};

package/dist/property/PropertyText.d.ts

@@ -0,0 +1,58 @@
+/**
+ * property/PropertyText.tsx
+ *
+ * 바로 고치는 글 칸 — 테두리 · 라벨 없는 칸이다. Enter(한 줄) · 칸 밖으로 나가면 저장, Esc 는 고치기 전으로 되돌린다.
+ * PropertyInput 은 칸만(값 영역 안에 다른 것과 함께 놓을 때), PropertyText 는 줄(PropertyRow) + 칸이다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import { type ReactNode } from "react";
+import type { SxProps, Theme } from "@mui/material";
+import { type PropertyAppearance } from "./appearance";
+import { type PropertyRowLayoutProps } from "./PropertyRow";
+import { type PropertyBindingProps } from "./binding";
+export interface PropertyInputProps extends PropertyBindingProps<string> {
+    placeholder?: string;
+    multiline?: boolean;
+    inputMode?: "text" | "tel" | "email" | "numeric" | "decimal" | "url" | "search" | "none";
+    maxLength?: number;
+    readOnly?: boolean;
+    /**
+     * 저장 전에 친 글을 바꾼다(전화번호 하이픈 · 8자리 날짜 등). null 을 돌려주면 틀린 값 — 저장하지 않고 되돌린다.
+     */
+    parse?: (raw: string) => string | null;
+    /** Esc 로 고치기를 물린다(창이 닫히지 않게 이벤트를 멈춘다). 기본 true. */
+    escapeReverts?: boolean;
+    /** 한글 조합 중의 Enter 에도 칸을 벗어난다(예전 업무함 동작). 기본 false — 조합을 마치는 Enter 는 그대로 둔다. */
+    blurOnComposingEnter?: boolean;
+    /** 칸 스타일 덧붙임(글자색 · 캐럿 색 등). */
+    sx?: SxProps<Theme>;
+    appearance?: PropertyAppearance;
+}
+/** 바로 고치는 글 칸(줄 없이 칸만). `form` + `name` 또는 `value` + `onCommit`. */
+export declare const PropertyInput: {
+    (props: PropertyInputProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export interface PropertyTextProps extends PropertyInputProps, Omit<PropertyRowLayoutProps, "sx" | "appearance"> {
+    icon?: ReactNode;
+    label: ReactNode;
+    /** 줄 루트 스타일(PropertyInput 의 sx 는 칸 스타일이다). */
+    rowSx?: SxProps<Theme>;
+    /** 칸 뒤에 붙일 것(단위 · 단추). */
+    endAdornment?: ReactNode;
+}
+/** 글 속성 줄 — 줄 + 바로 고치는 칸. */
+export declare function PropertyText({ icon, label, wide, full, rowStart, alignTop, rowSx, endAdornment, appearance, ...input }: PropertyTextProps): import("react/jsx-runtime").JSX.Element;
+/** 여러 줄 글 속성 줄 — 한 줄을 다 쓰고 라벨을 위에 붙인다(메모 · 비고). */
+export declare function PropertyTextArea(props: Omit<PropertyTextProps, "multiline">): import("react/jsx-runtime").JSX.Element;
+/** 날짜 값 — YYYY-MM-DD 이거나 비었다. */
+export declare function isDateText(value: string): boolean;
+/** 숫자만 적은 날짜(20261016)는 하이픈을 넣어 받는다 — 날짜 칸에 숫자만 치는 사람이 많다. */
+export declare function normalizeDateText(value: string): string;
+/** 날짜 칸의 기본 해석 — 8자리 숫자는 하이픈을 넣고, 꼴이 틀리면 null(되돌림). */
+export declare function parseDateText(raw: string): string | null;
+/** 날짜 속성 줄 — YYYY-MM-DD 로 적는다(8자리 숫자도 받는다). 꼴이 틀리면 저장하지 않고 되돌린다. */
+export declare function PropertyDate({ placeholder, parse, maxLength, ...props }: PropertyTextProps): import("react/jsx-runtime").JSX.Element;

package/dist/property/appearance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * property/appearance.ts
+ *
+ * 속성 줄(아이콘 + 라벨 | 값)의 모양 값 — 앱 전체는 `FormControlsConfigProvider property={...}` 로, 한 줄은 `appearance` prop 으로 바꾼다.
+ * 기본값은 업무함(taskham) 고객 · 거래처 · 직원 상세의 값이다(라벨 14px — 14px 아래 글자를 쓰지 않는 규칙).
+ * 업무함 패키지(@ehfuse/taskbox)는 줄 높이 32 · 라벨 104 · 값 14px · 누를 수 있는 줄만 호버 바탕인 자기 모양을 appearance 로 넘긴다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+/** 속성 줄 모양 값. */
+export interface PropertyAppearance {
+    /** 줄 최소 높이(px). 기본 30. */
+    rowMinHeight?: number;
+    /** 라벨 칸 폭(px). 기본 132 — "광고 수신 동의" 가 한 줄에 드는 폭. */
+    labelWidth?: number;
+    /** 라벨 글자 크기(px). 기본 14. */
+    labelFontSize?: number;
+    /** 라벨 글자 색(MUI 팔레트 키 또는 CSS 색). 기본 "text.secondary". */
+    labelColor?: string;
+    /** 라벨 앞 아이콘 크기(px) — null 이면 아이콘에 준 크기를 그대로 둔다. 기본 18. */
+    labelIconSize?: number | null;
+    /** 라벨이 칸을 넘으면 말줄임하고 title 을 단다(false 면 글을 그대로 둔다 — 줄바꿈될 수 있다). 기본 true. */
+    labelEllipsis?: boolean;
+    /** 값 칸(과 그 안의 바로 고치는 칸) 글자 크기(px). 기본 15. */
+    valueFontSize?: number;
+    /** 값 칸 최소 높이(px) — null 이면 두지 않는다. 기본 28. */
+    valueMinHeight?: number | null;
+    /** 값 칸 위아래 안쪽 여백(MUI spacing 단위). 기본 0. */
+    valuePaddingY?: number;
+    /** 값 칸 호버 · 포커스 바탕. 기본 "#f2f2f0". */
+    hoverBg?: string;
+    /** true 면 누를 수 있는 줄(onClick)에만 호버 바탕을 칠하고 포커스 바탕은 없다. 기본 false(모든 줄 · 포커스에도). */
+    hoverOnlyClickable?: boolean;
+    /** 누를 수 없는 값 칸의 커서. 기본 "text". */
+    idleCursor?: string;
+    /** 빈 값 · placeholder 색. 기본 "#9a9a97". */
+    placeholderColor?: string;
+    /** 바로 고치는 칸의 줄 간격 — "inherit" 이면 값 칸을 따른다. 기본 1.6. */
+    inputLineHeight?: number | string;
+    /** 고르기 메뉴 줄 글자 크기(px). 기본 15. */
+    menuFontSize?: number;
+}
+/** 기본 모양(taskham 의 상세 화면 값). */
+export declare const DEFAULT_PROPERTY_APPEARANCE: Required<PropertyAppearance>;
+/** 줄 값 → 앱 기본값(FormControlsConfig.property) → 패키지 기본값 순으로 합친다. */
+export declare function usePropertyAppearance(own?: PropertyAppearance): Required<PropertyAppearance>;

package/dist/property/binding.d.ts

@@ -0,0 +1,39 @@
+/**
+ * property/binding.tsx
+ *
+ * 속성 칸의 두 가지 쓰임을 하나로 잇는다.
+ *   (a) `form` + `name` — forma 폼의 그 칸만 구독한다(`form.useValue(name)`). 다른 칸이 바뀌어도 이 줄은 다시 그리지 않는다.
+ *       name 에 점 경로("career.0.title")를 주면 반복 줄의 한 칸만 구독한다(forma 는 그 경로 · 조상 · 자손에게만 알린다).
+ *       고치면 폼 값을 먼저 바꾸고(바로 보이게) `onCommit(value, name)` 을 부른다 — false 를 돌려주면 폼 값을 되돌린다.
+ *   (b) `value` + `onCommit` — 폼 없이 바깥이 값을 쥔다(업무함의 task 객체처럼).
+ * mfc 의 다른 칸처럼 `form` 이 있으면 폼 쪽 부품으로 갈라 그린다 — 훅을 조건부로 부르지 않으려는 것이다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import type { ComponentType } from "react";
+import type { FormLike } from "../types";
+/** 고친 값을 받는 콜백 — false(또는 false 로 끝나는 Promise)면 고치기 전으로 되돌린다. */
+export type PropertyCommitHandler<V> = (value: V, name?: string) => boolean | void | Promise<boolean | void>;
+/** 값 칸 공통 바인딩 props. */
+export interface PropertyBindingProps<V> {
+    /** forma 폼(useForm · useGlobalForm). 주면 name 의 값을 구독한다. */
+    form?: FormLike | null;
+    /** 폼 칸 이름(점 경로 가능 — "extra.size", "career.0.title"). */
+    name?: string;
+    /** 폼 없이 쓸 때의 값. */
+    value?: V;
+    /** 고친 값 — 값이 실제로 바뀌었을 때만 부른다. 바로 저장하는 화면은 여기서 저장한다. */
+    onCommit?: PropertyCommitHandler<V>;
+}
+/** 폼 칸 값을 쓴다 — setFormValue 가 있으면 그것을, 없으면 handleFormChange 를 이벤트 꼴로 부른다. */
+export declare function writeFormValue(form: FormLike, name: string, value: unknown): void;
+/**
+ * 값 칸 부품을 폼 바인딩으로 감싼다 — Base 는 늘 (b) 꼴(value + onCommit)만 안다.
+ * normalize 는 폼 값(undefined · null 등)을 칸이 아는 꼴로 바꾼다.
+ */
+export declare function withPropertyForm<V, P extends PropertyBindingProps<V>>(Base: ComponentType<P>, normalize: (raw: unknown) => V, displayName: string): {
+    (props: P): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/property/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * property — 속성 화면 부품(아이콘 + 라벨 | 값, 값을 눌러 그 자리에서 고친다).
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+export { DEFAULT_PROPERTY_APPEARANCE, usePropertyAppearance } from "./appearance";
+export type { PropertyAppearance } from "./appearance";
+export { PropertyRow, PropertyGrid, PropertyEmpty, PROPERTY_GRID_TWO_COLUMN_MIN, PROPERTY_GRID_FOUR_COLUMN_MIN, PROPERTY_GRID_FOUR_CQ, } from "./PropertyRow";
+export type { PropertyRowProps, PropertyRowLayoutProps, PropertyGridProps } from "./PropertyRow";
+export { withPropertyForm, writeFormValue } from "./binding";
+export type { PropertyBindingProps, PropertyCommitHandler } from "./binding";
+export { PropertyInput, PropertyText, PropertyTextArea, PropertyDate, isDateText, normalizeDateText, parseDateText } from "./PropertyText";
+export type { PropertyInputProps, PropertyTextProps } from "./PropertyText";
+export { PropertySelect, PropertyMultiSelect, PropertySwitch } from "./PropertySelect";
+export type { PropertyOption, PropertySelectValue, PropertySelectProps, PropertyMultiSelectProps, PropertySwitchProps } from "./PropertySelect";
+export { PropertyAddress, PropertyAddressInput } from "./PropertyAddress";
+export type { PropertyAddressProps, PropertyAddressInputProps } from "./PropertyAddress";

package/package.json

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