@ehfuse/mui-form-controls 3.4.5 → 3.5.1

package/README.md

@@ -428,6 +428,48 @@ import { ToggleButtonGroup } from "@ehfuse/mui-form-controls";
 />;
 ```
 
+## Property (속성 화면) — v3.5.0
+
+노션풍 상세 화면의 "아이콘 + 라벨 | 값" 줄이다. 값을 눌러 그 자리에서 고치고 **칸에서 벗어날 때(blur · Enter) 바로 저장**한다.
+묶음(`PropertyGrid`)은 화면 폭이 아니라 **묶음의 폭**(컨테이너 쿼리)으로 1열 → 2열(560px~) → 4열(1180px~)이 된다.
+
+| 부품 | 설명 |
+| --- | --- |
+| `PropertyGrid` | 줄 묶음(1 · 2 · 4열). `twoColumnMin` · `fourColumnMin` 으로 경계를 바꾼다 |
+| `PropertyRow` | 한 줄 틀 — `icon` · `label` · `onClick(anchor)`(값을 누르면 메뉴를 여는 줄) · `wide` · `full` · `rowStart` · `alignTop` · `sx` · `valueSx`. 값은 children |
+| `PropertyInput` | 줄 없이 바로 고치는 칸만(값 영역 안에 다른 것과 함께 둘 때) |
+| `PropertyText` · `PropertyTextArea` · `PropertyDate` | 글 · 여러 줄 글 · 날짜(YYYY-MM-DD, 8자리 숫자도 받음, 틀리면 되돌림) 줄 |
+| `PropertySelect` · `PropertyMultiSelect` | 고르기 메뉴(효과 없이 바로 뜸). `onCreate` 를 주면 찾기 칸 + 쳐서 새 항목 |
+| `PropertySwitch` | 켜고 끄기 — 누르는 즉시 저장 |
+| `PropertyAddress` · `PropertyAddressInput` | 주소 — 고쳐 적거나 돋보기로 우편번호 검색 |
+| `PropertyEmpty` | 옅은 "비어 있음" |
+
+### 두 가지 쓰임 — `form` + `name`, 또는 `value` + `onCommit`
+
+```tsx
+// (a) forma 폼 — 그 칸만 구독한다(다른 칸이 바뀌어도 이 줄은 다시 그리지 않는다).
+<PropertyGrid>
+    <PropertyText icon={<PhoneIcon />} label="전화" form={form} name="phone" onCommit={(value, name) => save({ [name!]: value })} />
+    {/* 점 경로 — 반복 줄의 한 칸만 구독한다 */}
+    <PropertyText icon={<WorkIcon />} label="회사" form={form} name="career.0.company" onCommit={saveCareer} />
+    <PropertySelect icon={<CategoryIcon />} label="분류" form={form} name="kind" options={kinds} emptyLabel="지정 안 함" onCommit={saveKind} />
+</PropertyGrid>
+
+// (b) 폼 없이 — 바깥이 값을 쥔다.
+<PropertyText icon={<PlaceIcon />} label="장소" value={task.place} placeholder="비어 있음" onCommit={(next) => patch({ place: next })} />
+```
+
+- `form` 쪽은 고친 값을 **폼에 먼저 적고**(`setFormValue` · 없으면 `handleFormChange`) `onCommit(value, name)` 을 부른다.
+- `onCommit` 이 `false`(또는 `false` 로 끝나는 Promise)를 돌려주면 고치기 전으로 되돌린다(폼 값도). 값이 실제로 바뀌었을 때만 부른다.
+- `PropertyText` 의 `parse(raw)` 는 저장 전에 친 글을 바꾼다(전화번호 하이픈 등) — `null` 이면 틀린 값으로 보고 되돌린다.
+- 예전 이름 `onChange`(Select · MultiSelect · Switch) · `checked`(Switch)도 그대로 받는다.
+
+### 모양 — `FormControlsConfigProvider property` · `appearance`
+
+기본값: 줄 30px · 라벨 132px/14px/`text.secondary` · 값 15px · 값 칸 28px · 호버 `#f2f2f0` · 빈 글 `#9a9a97` · 메뉴 15px.
+앱 전체는 `<FormControlsConfigProvider property={{ rowMinHeight: 32, labelWidth: 104 }}>`, 한 줄은 `appearance={...}` 로 바꾼다
+(`hoverOnlyClickable` · `idleCursor` · `labelEllipsis` · `labelIconSize` · `valuePaddingY` · `inputLineHeight` 등 — 타입 `PropertyAppearance`).
+
 ## 문서 / Documentation
 
 - [한국어 문서](./docs/ko/getting-started.md)

package/dist/FormControlsConfig.d.ts

@@ -13,13 +13,17 @@
  * @author 김영진 (ehfuse@gmail.com)
  */
 import { type ReactNode } from "react";
+import type { PropertyAppearance } from "./property/appearance";
 /** 앱 전체 기본값. */
 export interface FormControlsConfig {
     pickerCentered?: boolean;
     timePickerVariant?: TimePickerVariant;
+    property?: PropertyAppearance;
 }
 /** 시간 고르는 방식 — "list" 숫자 목록(기본) · "wheel" [오전/오후][시][분] 바퀴. */
 export type TimePickerVariant = "list" | "wheel";
+/** 기본값 문맥(Provider 가 없으면 빈 객체 — 예전 동작). */
+export declare const FormControlsConfigContext: import("react").Context<FormControlsConfig>;
 /** 앱 전체 기본값을 건다. */
 export declare function FormControlsConfigProvider({ children, ...config }: FormControlsConfig & {
     children: ReactNode;

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { FormControlsConfigProvider, usePickerCentered, useTimePickerVariant } from "./FormControlsConfig";
 export type { FormControlsConfig, TimePickerVariant } from "./FormControlsConfig";
+export * from "./property";
 export { SearchTextField } from "./SearchTextField";
 export { ClearTextField } from "./ClearTextField";
 export { TagsTextField } from "./TagsTextField";