@iyulab/modern-app 0.18.17 → 0.18.19

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.18.19] - 2026-09-04
+
+### Added
+
+- **`SidebarLayout` had no way for a consumer to control scroll position on route
+  change, and no official way to reach its scroll container at all** — only an
+  undocumented shadow-DOM `part="main"` selector, a style-only CSS hook rather than a
+  JS access contract. Added `layout.scrollBehavior(context, main)`, called on every
+  `route-done` before focus moves to the container, and a public `mainElement`
+  accessor on the element for reading/writing scroll position outside the hook (e.g.
+  saving a position from a `route-begin` listener). Unset `scrollBehavior` does
+  nothing, matching Vue Router's own default for an unset `scrollBehavior`.
+
+## [0.18.18] - 2026-09-04
+
+### Fixed
+
+- **The React JSX declaration for `<u-info-field>`'s `value` prop was narrowed to
+  `string`, while the component's own class field type (`unknown`) and documented
+  behavior explicitly accept `null` and numbers.** TypeScript-strict consumers hit
+  `TS2322` passing a nullable or numeric value — a very common shape for
+  API-sourced data — even though rendering already coerces whatever is passed via
+  `String()`/the format helpers. Widened the JSX type to `unknown` to match. Added
+  a compile-only regression fixture (`tests/types/react-consumption.tsx`) covering
+  the `string | null` and `number | undefined` shapes that previously failed.
+
 ## [0.18.17] - 2026-09-03
 
 ### Fixed

package/dist/components/InfoField.d.ts

@@ -98,7 +98,9 @@ declare module 'react' {
         interface IntrinsicElements {
             'u-info-field': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
                 label?: string;
-                value?: string;
+                /** 클래스 필드와 동일하게 `unknown` — 렌더 로직이 `String(value)`/포맷터로 무엇이
+                 *  오든 처리하므로 `null`·숫자를 그대로 넘길 수 있다(위 클래스 필드 JSDoc 참조). */
+                value?: unknown;
                 blank?: string;
                 numeric?: boolean;
                 format?: InfoFieldFormat;

package/dist/layouts/SidebarLayout.d.ts

@@ -14,6 +14,13 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     progressBarEl: UProgressBar;
     /** 현재 라우터 컨텍스트 */
     context: RouteContext | null;
+    /**
+     * 라우트 컨텐츠의 실제 스크롤 컨테이너(섀도 DOM `[part="main"]`). `scrollTop`을 읽어
+     * 위치를 저장하거나, 써서 복원한다 — `part="main"`은 스타일링용 CSS 훅일 뿐 JS 접근
+     * 계약이 아니었으므로, 소비자가 이 컨테이너에 안정적으로 접근할 공식 수단으로 신설.
+     * 아직 렌더 전이면 `null`.
+     */
+    get mainElement(): HTMLElement | null;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changedProperties: PropertyValues): void;

package/dist/layouts/SidebarLayout.js

@@ -40,7 +40,9 @@ var v = class extends i {
 		}, this.handleRouteDone = (e) => {
 			this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible");
-			}, 300), (this.shadowRoot?.querySelector(".main"))?.focus({ preventScroll: !0 });
+			}, 300);
+			let t = this.shadowRoot?.querySelector(".main");
+			t && (this.config?.scrollBehavior?.(e.context, t), t.focus({ preventScroll: !0 }));
 		}, this.handleRouteError = (e) => {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
@@ -82,6 +84,9 @@ var v = class extends i {
 	static {
 		this.styles = [super.styles, o];
 	}
+	get mainElement() {
+		return this.shadowRoot?.querySelector(".main") ?? null;
+	}
 	connectedCallback() {
 		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("route-error", this.handleRouteError), window.addEventListener("screen-resize", this.handleScreenResize);
 	}

package/dist/layouts/SidebarLayout.types.d.ts

@@ -1,4 +1,5 @@
 import { TemplateResult } from 'lit';
+import { RouteContext } from '@iyulab/router';
 import { StyleMap } from '../internals/StyledElement';
 import { SidebarLinkConfig } from '../components/SidebarLink';
 import { SidebarSectionConfig } from '../components/SidebarSection';
@@ -55,6 +56,14 @@ export interface SidebarLayoutConfig {
      * 미지정 시 필터링하지 않는다(모든 항목 표시). 보통 `@iyulab/enterprise` 의 `hasPermission` 을 넘긴다.
      */
     hasPermission?: (code: string) => boolean;
+    /**
+     * 라우트 전환이 끝날 때(`route-done`, 포커스가 메인 스크롤 컨테이너로 옮겨지기 직전)
+     * 호출된다 — 새 라우트의 `RouteContext`와 그 스크롤 컨테이너(`SidebarLayout.mainElement`와
+     * 동일 엘리먼트)를 받는다. 스크롤 위치를 리셋·저장·복원하는 로직은 이 훅 안에서 직접
+     * 구현한다(예: 목록→상세로 갔다가 돌아올 때 스크롤 위치 복원). 미지정 시 기본값은
+     * "아무것도 안 함" — Vue Router의 `scrollBehavior` 미지정 기본값과 동일하다(breaking 아님).
+     */
+    scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
     /** 사이드바 스타일 맵 */
     styles?: StyleMap<SidebarParts>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.18.17",
+  "version": "0.18.19",
   "keywords": [
     "iyulab",
     "web-framework",

package/skills/modern-app/references/layout.md

@@ -24,6 +24,9 @@ interface SidebarLayoutConfig {
   /** Permission filter — hides items (and emptied section/groups) whose requirement fails. Unset shows everything. See "권한 기반 메뉴 필터" below. */
   hasPermission?: (code: string) => boolean;
 
+  /** Called on `route-done` (before focus moves to the container) with the new route's `RouteContext` and the scroll container itself — implement reset/save/restore here. Unset does nothing (same default as Vue Router's unset `scrollBehavior`). Also reachable outside the hook via the element's `.mainElement` accessor. */
+  scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
+
   /** Per-part style overrides (CSS custom properties / inline styles). */
   styles?: StyleMap<SidebarParts>;
 }