@iyulab/enterprise 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.13.0
+
+### Changed
+
+- **`FormRow`'s grid tracks are now `minmax(0, 1fr)` rather than `1fr`, so columns declared
+  equal actually render equal.** A grid item's default `min-width: auto` refuses to shrink below
+  its content's min-content width, so one long value in a row was enough to blow out its own
+  column and squeeze the rest. Measured in a 400px container with one long unbreakable string:
+  a two-column row laid out at **425px / 8px** and a three-column row at **425px / 8px / 8px**,
+  and the row overflowed its container. With `minmax(0, 1fr)` the same cases lay out at
+  **196 / 196** and **128 / 128 / 128**. Nothing about the API changes, and rows whose content
+  already fit are unaffected.
+  - Long unbreakable content still overflows its own column — that is a separate axis, handled
+    on the cell with `overflow-wrap` (this package's peer elements already set it).
+
+- **`@iyulab/components` is no longer an optional peer dependency.** The main entry imports it
+  unconditionally, so declaring it optional meant a consumer installing this package alone got
+  nothing installed and no warning — the failure surfaced only as a module-not-found at
+  runtime. Consumers already installing it are unaffected.
+
+## 0.12.0
+
+### Added
+
+- **`ApiError.details`** — OData v4 error envelopes carry per-field validation
+  errors in `error.details`, and `ODataService` already parsed that envelope to
+  build `ApiError.message`, but discarded the rest of the same parse. `ApiError`
+  now also carries `details` (`ApiErrorDetail[] | undefined`), so a caller can
+  bind server-side validation failures to the fields that produced them instead
+  of showing one flattened string. Backward compatible: callers that never read
+  `.details` are unaffected.
+  - Per the OData JSON Format v4.0 spec each detail entry MUST have `code` and
+    `message` and MAY have `target`, so `target` is optional on `ApiErrorDetail`
+    and entries that lack a string `code`/`message` are dropped; when nothing
+    usable remains `details` is `undefined` rather than an empty array.
+- **`formatError(info)` now receives `details`** — the callback that shapes the
+  user-facing message previously got only `rawMessage` and the raw `body`, so an
+  app wanting to summarize per-field failures had to re-dig and re-validate the
+  same `error.details` the service had just parsed. `info` now carries the
+  validated array alongside the derived `rawMessage` it already had. Purely
+  additive to a callback input: existing implementations ignore the new field.
+
 ## 0.11.1
 
 ### Fixed

package/README.md

@@ -18,7 +18,7 @@ npm install @iyulab/enterprise
 | `FormRow` | React | 2컬럼 그리드 폼 행(`full`로 1컬럼) |
 | `ApiConfig` | class | baseUrl/OData·API prefix·dev 판별 중앙 설정 |
 | `createODataService` | factory | OData v4 + custom REST CRUD 서비스(401·토스트·에러파싱) |
-| `ApiError` | class | HTTP status 를 실은 API 호출 실패 에러 |
+| `ApiError` | class | HTTP status + OData `error.details`(필드별 검증 상세)를 실은 API 호출 실패 에러 |
 | `createAuthClient` | factory | 쿠키 세션 인증(fetchMe/login/logout) — 제네릭 user/자격증명 |
 | `createPermissionStore` · `hasPermission` 외 | store | 권한 스냅샷 store + 판정 free 함수 |
 | `CurrencyHelper` | class | 통화 포맷(`formatKRW` 등) |
@@ -51,6 +51,8 @@ import { FormSection, FormRow } from '@iyulab/enterprise'
 ```
 
 - `FormRow`는 기본 2컬럼 그리드입니다. 한 칸을 차지하려면 `full`을, 다른 열 수가 필요하면 `columns`를 씁니다.
+- **열 폭 — 선언한 열은 실제로 균등합니다.** 트랙은 `1fr`이 아니라 `minmax(0, 1fr)`입니다. 그리드 아이템의 기본 `min-width: auto`는 내용의 min-content 아래로 줄어들기를 거부해서, 순수 `1fr`로 두면 긴 내용이 든 칸만 부풀고 나머지가 찌그러집니다(400px 컨테이너 실측: 2열 **425/8**, 3열 **425/8/8**). `minmax(0, 1fr)`은 트랙 최소를 0으로 만들어 같은 경우를 **196/196**·**128/128/128**로 만듭니다.
+- ⚠**긴 불가분 문자열 자체의 넘침은 별개 축입니다.** 칸이 균등해져도 그 안의 긴 문자열은 자기 칸을 넘습니다 — 셀 쪽에서 `overflow-wrap`으로 다룹니다(`@iyulab/components`의 엘리먼트는 이미 그 값을 갖습니다).
 - 두 컴포넌트 모두 `className`·`style`을 받아 기본값 **뒤에** 병합합니다 — 블록을 복제하지 않고 조정하는 정규 경로입니다. `FormSection`은 제목 줄만 바꾸는 `titleStyle`도 받습니다.
 
 ```tsx
@@ -121,10 +123,34 @@ await svc.apiPost<Order>('orders/7/attachments', form)
 | `onUnauthorized(status)` | 401 시 호출 — 리다이렉트/재진입 가드는 앱이 처리 |
 | `notify.success/error` | 토스트 훅 (생략 시 토스트 없음 — 순수) |
 | `messages` | 사용자 대면 문구 (기본 영어, 지정 키만 대체) |
-| `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) |
+| `formatError(info)` | 에러 메시지 포매팅 오버라이드 (앱별 정책) — `info` 는 `status`/`statusText`/`rawMessage`/`details`(검증된 `error.details`)/`body` 를 받는다 |
 
 > 도메인 액션(상태 전이 등)·엔티티 목록·권한 코드는 라이브러리에 넣지 말고 앱 adapter 에 둔다.
 
+#### 실패 응답 — `ApiError`
+
+모든 메서드는 실패 시 `ApiError`(`Error` 상속)를 던진다. `status` 로 상태별 분기하고,
+서버가 OData v4 오류 봉투에 필드별 검증 상세(`error.details`)를 실어 보내면 `details` 로
+읽어 폼의 필드별 오류 표시에 바로 연결할 수 있다.
+
+```typescript
+try {
+  await svc.odataPost('Roles', draft)
+} catch (e) {
+  if (e instanceof ApiError && e.details) {
+    // [{ code: 'ValidationError', message: 'The Name field is required.', target: 'Name' }, …]
+    for (const d of e.details) markFieldError(d.target, d.message)
+  }
+}
+```
+
+| 필드 | 설명 |
+|------|------|
+| `message` | 사용자 대면 메시지 (`formatError` → 서버 raw → status 폴백 순으로 결정) |
+| `status` | HTTP status |
+| `details` | `error.details` 항목 배열 — 규격상 `code`/`message` 는 필수, `target`(속성 이름)은 선택. 상세가 없거나 규격 형태가 아니면 `undefined` |
+
+
 ### 인증 + 권한 (`createAuthClient` · 권한 store)
 
 쿠키 세션 인증 흐름과 권한 스냅샷을 승격. 사용자·자격증명 **형태는 앱이 제네릭으로 정의**하고, 권한 코드는 불투명 문자열로만 다룬다. `getPermissions` 를 주면 로그인/세션 조회 성공 시 권한 store 가 자동 갱신된다.

package/dist/FormRow.d.ts

@@ -5,6 +5,22 @@ import { CSSProperties, ReactNode } from 'react';
  * 오버라이드 계약(docs/lob-layers.md §2)에 따라 `className`·`style` 을 받아 병합한다.
  * `columns` 는 2열 고정이 맞지 않는 소비자가 **컴포넌트를 복제하지 않고** 조정하는 경로다
  * — 복제가 시작되면 이 계층은 쓰기 전보다 나쁜 상태를 만든다.
+ *
+ * 🔴**트랙은 `minmax(0, 1fr)` 이지 `1fr` 이 아니다 — 순수 `1fr` 은 «균등» 을 약속하고**
+ * **지키지 않는다.** 그리드 아이템의 기본 `min-width: auto` 는 내용의 min-content 아래로
+ * 줄어들기를 거부하므로, 한 칸에 긴 내용이 들어오면 그 칸만 부풀고 나머지가 찌그러진다.
+ * 실측(400px 컨테이너 · 한 칸에 긴 불가분 문자열): 2열이 **425/8**, 3열이 **425/8/8** 이었고
+ * 행 자체가 컨테이너를 넘쳤다. `minmax(0, 1fr)` 은 트랙의 최소를 0 으로 만들어 **자식을**
+ * **건드리지 않고** 이를 고친다 — 같은 실측에서 **196/196** · **128/128/128**.
+ *
+ * ⚠**긴 불가분 내용 자체의 넘침은 별개 축이고 이 컴포넌트의 몫이 아니다.** 칸이 균등해져도
+ * 그 안의 긴 문자열은 여전히 자기 칸을 넘는다 — 그것은 셀의 `overflow-wrap` 이 답이다
+ * (`@iyulab/components` 의 엘리먼트는 이미 그 값을 갖는다). 같은 실측에서 `overflow-wrap` 을
+ * 주면 행의 넘침이 0 이 됐다.
+ *
+ * 계약은 `tests/form-layout-contract.test.ts` 가 고정한다 — 다만 그 파일은 **«선언» 을 재지**
+ * **«배치» 를 재지 않는다**(이 패키지엔 레이아웃을 계산하는 테스트 자리가 없다). 위 수치는
+ * 형제 패키지의 브라우저 프로젝트를 계측기로 빌린 일회성 탐침으로 쟀다.
  */
 export declare function FormRow({ children, full, columns, className, style, }: {
     children: ReactNode;

package/dist/data/ODataService.d.ts

@@ -1,11 +1,25 @@
 import { HttpResponse } from '@iyulab/http-client';
+/**
+ * OData v4 오류 봉투의 `error.details` 항목 — 필드별 검증 실패 상세.
+ *
+ * 규격(OData JSON Format v4.0)상 각 항목은 `code`/`message` 를 **반드시** 갖고
+ * `target`(오류가 난 속성 이름)은 **선택**이다 — 필수로 선언하면 target 을 생략한
+ * 서버 응답에서 타입이 거짓말을 하게 된다.
+ */
+export interface ApiErrorDetail {
+    code: string;
+    message: string;
+    target?: string;
+}
 /**
  * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
  * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
  */
 export declare class ApiError extends Error {
     readonly status: number;
-    constructor(message: string, status: number);
+    /** OData v4 오류 봉투의 `error.details`(필드별 검증 상세) — 서버 응답에 없거나 파싱 실패면 undefined. */
+    readonly details?: ApiErrorDetail[];
+    constructor(message: string, status: number, details?: ApiErrorDetail[]);
 }
 /** 서비스가 토스트/에러에 쓰는 사용자 대면 문구. 기본값은 영어 — 앱이 로케일별로 오버라이드한다. */
 export interface ODataServiceMessages {
@@ -49,6 +63,8 @@ export interface ODataServiceConfig {
         status: number;
         statusText: string;
         rawMessage?: string;
+        /** OData v4 `error.details` — 검증을 마친 항목만 실린다(`ApiError.details` 와 같은 값). */
+        details?: ApiErrorDetail[];
         body?: unknown;
     }) => string | undefined;
 }

package/dist/index.js

@@ -59,6 +59,22 @@ function FormSection({ title, children, className, style, titleStyle }) {
 * 오버라이드 계약(docs/lob-layers.md §2)에 따라 `className`·`style` 을 받아 병합한다.
 * `columns` 는 2열 고정이 맞지 않는 소비자가 **컴포넌트를 복제하지 않고** 조정하는 경로다
 * — 복제가 시작되면 이 계층은 쓰기 전보다 나쁜 상태를 만든다.
+*
+* 🔴**트랙은 `minmax(0, 1fr)` 이지 `1fr` 이 아니다 — 순수 `1fr` 은 «균등» 을 약속하고**
+* **지키지 않는다.** 그리드 아이템의 기본 `min-width: auto` 는 내용의 min-content 아래로
+* 줄어들기를 거부하므로, 한 칸에 긴 내용이 들어오면 그 칸만 부풀고 나머지가 찌그러진다.
+* 실측(400px 컨테이너 · 한 칸에 긴 불가분 문자열): 2열이 **425/8**, 3열이 **425/8/8** 이었고
+* 행 자체가 컨테이너를 넘쳤다. `minmax(0, 1fr)` 은 트랙의 최소를 0 으로 만들어 **자식을**
+* **건드리지 않고** 이를 고친다 — 같은 실측에서 **196/196** · **128/128/128**.
+*
+* ⚠**긴 불가분 내용 자체의 넘침은 별개 축이고 이 컴포넌트의 몫이 아니다.** 칸이 균등해져도
+* 그 안의 긴 문자열은 여전히 자기 칸을 넘는다 — 그것은 셀의 `overflow-wrap` 이 답이다
+* (`@iyulab/components` 의 엘리먼트는 이미 그 값을 갖는다). 같은 실측에서 `overflow-wrap` 을
+* 주면 행의 넘침이 0 이 됐다.
+*
+* 계약은 `tests/form-layout-contract.test.ts` 가 고정한다 — 다만 그 파일은 **«선언» 을 재지**
+* **«배치» 를 재지 않는다**(이 패키지엔 레이아웃을 계산하는 테스트 자리가 없다). 위 수치는
+* 형제 패키지의 브라우저 프로젝트를 계측기로 빌린 일회성 탐침으로 쟀다.
 */
 function FormRow({ children, full, columns = 2, className, style }) {
 	if (full) return /* @__PURE__ */ jsx("div", {
@@ -73,7 +89,7 @@ function FormRow({ children, full, columns = 2, className, style }) {
 		className,
 		style: {
 			display: "grid",
-			gridTemplateColumns: `repeat(${columns}, 1fr)`,
+			gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
 			gap: "var(--u-space-sm, 8px)",
 			...style
 		},
@@ -613,14 +629,31 @@ var ApiConfig = class {
 * const rows = await svc.odataGet<BankAccount>('BankAccounts', { $top: '20' })
 */
 /**
+* `error.details` 를 검증해 추출한다 — 규격이 요구하는 형태(`code`/`message` 둘 다 문자열)를
+* 갖춘 항목만 남긴다. 이 파일이 `error.message` 에 이미 적용하는 규칙(`typeof === "string"` 을
+* 확인한 뒤 사용)과 같은 이유다: 검증 없이 캐스팅하면 타입만 맞고 런타임에 호출부가 깨진다.
+* 쓸 수 있는 항목이 하나도 없으면 undefined 로 정규화한다 — 빈 배열을 주면 호출부의
+* `if (e.details)` 가 참이 되어 "상세가 있다"고 오해한다.
+*/
+function extractErrorDetails(raw) {
+	if (!Array.isArray(raw)) return void 0;
+	const details = raw.filter((d) => {
+		if (typeof d !== "object" || d === null) return false;
+		const rec = d;
+		return typeof rec.code === "string" && typeof rec.message === "string";
+	});
+	return details.length > 0 ? details : void 0;
+}
+/**
 * API 호출 실패 에러 — HTTP status 를 실어 호출부가 상태별 분기(예: 404 도메인 문구)를 할 수 있게 한다.
 * `Error` 를 상속하므로 기존 `e instanceof Error`/`e.message` 소비처는 그대로 동작한다.
 */
 var ApiError = class extends Error {
-	constructor(message, status) {
+	constructor(message, status, details) {
 		super(message);
 		this.name = "ApiError";
 		this.status = status;
+		this.details = details;
 	}
 };
 var DEFAULT_MESSAGES = {
@@ -674,27 +707,39 @@ function createODataService(config) {
 		const clean = path.startsWith("/") ? path.slice(1) : path;
 		return `${baseUrl}/${apiPrefix}/${clean}`;
 	};
-	/** OData 응답에서 사용자 친화적 에러 메시지 추출. */
-	async function extractErrorMsg(res) {
+	/** OData 응답에서 사용자 친화적 에러 메시지 + 구조화된 필드별 상세를 추출. */
+	async function extractErrorInfo(res) {
 		let body;
 		try {
 			body = await res.json();
 		} catch {
 			body = void 0;
 		}
-		const rawVal = (body?.error)?.message ?? body?.message ?? body?.Message;
+		const errorObj = body?.error;
+		const rawVal = errorObj?.message ?? body?.message ?? body?.Message;
 		const rawMessage = typeof rawVal === "string" ? rawVal : void 0;
+		const details = extractErrorDetails(errorObj?.details);
 		if (config.formatError) {
 			const m = config.formatError({
 				status: res.status,
 				statusText: res.statusText,
 				rawMessage,
+				details,
 				body
 			});
-			if (m) return m;
+			if (m) return {
+				message: m,
+				details
+			};
 		}
-		if (rawMessage && rawMessage.length <= 200) return rawMessage;
-		return messages.http[res.status] ?? `${messages.requestFailed} (${res.status})`;
+		if (rawMessage && rawMessage.length <= 200) return {
+			message: rawMessage,
+			details
+		};
+		return {
+			message: messages.http[res.status] ?? `${messages.requestFailed} (${res.status})`,
+			details
+		};
 	}
 	/** 에러 확인 후 throw. 401 은 onUnauthorized 통지 후 세션 만료 에러로 단락. */
 	async function throwIfError(res) {
@@ -703,7 +748,8 @@ function createODataService(config) {
 			config.onUnauthorized?.(401);
 			throw new ApiError(messages.sessionExpired, 401);
 		}
-		throw new ApiError(await extractErrorMsg(res), res.status);
+		const { message, details } = await extractErrorInfo(res);
+		throw new ApiError(message, res.status, details);
 	}
 	async function odataGet(entity, params) {
 		const u = new URL(odataUrl(entity));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/enterprise",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Enterprise utilities and components for iyulab framework",
   "keywords": [
     "enterprise",
@@ -58,7 +58,7 @@
     "@iyulab/components": "^1.27.0",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.14",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10"
@@ -66,10 +66,5 @@
   "peerDependencies": {
     "react": ">=18",
     "@iyulab/components": ">=1.27.0"
-  },
-  "peerDependenciesMeta": {
-    "@iyulab/components": {
-      "optional": true
-    }
   }
 }