@iyulab/modern-app 0.34.1 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.35.0] - 2026-10-06
+
+### Changed
+
+- **Breaking — the JSX types for the plain content-primitive tags moved to `@iyulab/modern-app/react`.**
+  The main entry's type declarations imported `react`, so a TypeScript app without React (`react` is
+  an optional peer) failed to type-check with `skipLibCheck: false` — seven `TS2307: Cannot find
+  module 'react'` errors from `ActionBar`, `EmptyState`, `GroupBox`, `InfoField`, `InfoSection`,
+  `MasterDetailLayout` and `PageHeader`. The main entry no longer references React. A React app
+  that imports anything from `@iyulab/modern-app/react` keeps the tag types as before; one that
+  only writes the plain tags in JSX adds `import type {} from '@iyulab/modern-app/react'` once.
+
+### Documentation
+
+- **The Quick Start's menu icons render.** Its `icon: 'home'` / `'users'` had no `lib`, so they were
+  looked up in the app's own `/assets/icons/` and, in a fresh app, drawn as the placeholder. The
+  example now names `lib: 'tabler'`, and a new «Icons» section explains where names resolve from.
+- **`routerMode: 'hash'` is described** under Navigation, for static hosts that serve one document.
+- Requires `@iyulab/router` 0.19.1 for shell links to carry the `#` address on a first visit in hash mode.
+
+## [0.34.2] - 2026-10-06
+
+### Fixed
+
+- **The content area's scroll keys yield to the control that owns them** (`SidebarLayout`). With focus
+  on a button in the content, Space scrolled the page by a screen and the button never fired; with
+  focus in a widget that moves with the arrows itself (a tree, a menu, a radio group, a grid), each
+  arrow moved inside the widget and also scrolled the content. A key a widget already handled is left
+  alone, and Space on a button or link presses it.
+
 ## [0.34.1] - 2026-10-05
 
 ### Fixed

package/README.md

@@ -29,8 +29,8 @@ await app.load({
     logo: { src: '/assets/logo.svg', alt: 'My App' },
     title: 'My App',
     main: [
-      { type: 'link', icon: 'home',  label: 'Home',  href: '/' },
-      { type: 'link', icon: 'users', label: 'Users', href: '/users' },
+      { type: 'link', icon: 'home',  lib: 'tabler', label: 'Home',  href: '/' },
+      { type: 'link', icon: 'users', lib: 'tabler', label: 'Users', href: '/users' },
     ],
   },
   routes: [
@@ -45,6 +45,21 @@ await app.load({
 });
 ```
 
+### Icons
+
+A menu item's `icon` is a name resolved by `<u-icon>` from `@iyulab/components`:
+
+- **with `lib`** — from that library. `tabler`, `heroicons`, `lucide` and `bootstrap` are pre-registered
+  and fetched from a CDN on first use (the example above uses `tabler`); register your own with
+  `IconRegistry.register()`.
+- **without `lib`** — from your own files at `/assets/icons/<name>.svg` (change the folder with
+  `setDefaultBaseUrl()`).
+
+A name that resolves to nothing is drawn as a neutral placeholder instead of an empty gap, so a
+missing icon set shows up as every item having the same icon. The shell's own controls (menu and
+sidebar toggles, close) use a bundled set and need no network. See the components
+[icon guide](https://github.com/iyulab/node-components/blob/main/docs/icons.md).
+
 ## Skills Usage
 
 AI agent skills for this package are located in `skills/modern-app/`. Install them with `npx skills`:
@@ -69,6 +84,16 @@ app.router?.go('/users/42');   // via router instance
 app.router?.context;           // current RouteContext
 ```
 
+Routes live in the path (`/users/42`) by default, which needs the server to answer every path with
+the app. On a static host that serves one document (GitHub Pages, object storage), put the route
+after `#` instead:
+
+```typescript
+await app.load({ routerMode: 'hash', /* … */ });   // https://example.com/#/users/42
+```
+
+Links and `app.navigate()` follow the mode, so the rest of the app is written the same way.
+
 ### Theme
 
 ```typescript
@@ -214,6 +239,14 @@ properties that a raw element only handles correctly under React 19.
 npm install @iyulab/modern-app @lit/react react
 ```
 
+The JSX types for using the content primitives as plain tags (`<u-info-field>`, `<u-page-header>`, …)
+live in this subpath too, so a non-React app never needs React's types. Importing anything from
+`@iyulab/modern-app/react` brings them in; a React app that only uses the plain tags adds one line:
+
+```ts
+import type {} from '@iyulab/modern-app/react';
+```
+
 ```tsx
 import { SidebarLayout, Wizard, type SidebarItem, type WizardStep } from '@iyulab/modern-app/react';
 

package/dist/components/ActionBar.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'danger' | 'main';
 /**
  * 푸터 액션 바 — 상세·편집 화면 맨 아래의 같은 골격.
@@ -43,13 +42,4 @@ declare global {
         'u-action-bar': ActionBar;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-action-bar': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                sticky?: boolean;
-            };
-        }
-    }
-}
 export {};

package/dist/components/EmptyState.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'icon' | 'title' | 'description' | 'actions';
 /**
  * 빈 상태 — 목록·검색 결과가 비었을 때.
@@ -50,16 +49,4 @@ declare global {
         'u-empty-state': EmptyState;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-empty-state': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                variant?: 'no-data' | 'no-results';
-                title?: string;
-                description?: string;
-                locale?: string;
-            };
-        }
-    }
-}
 export {};

package/dist/components/GroupBox.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'header' | 'title' | 'meta' | 'description' | 'actions' | 'body';
 /** 제목 단계 — 페이지 제목(h1)은 `u-page-header` 몫이라 2 부터다. */
 export type GroupBoxLevel = 2 | 3 | 4 | 5 | 6;
@@ -66,18 +65,4 @@ declare global {
         'u-group-box': GroupBox;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-group-box': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                title?: string;
-                divider?: boolean;
-                flush?: boolean;
-                level?: GroupBoxLevel;
-                meta?: string;
-                description?: string;
-            };
-        }
-    }
-}
 export {};

package/dist/components/InfoField.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'label' | 'value' | 'unit' | 'trend';
 export type InfoFieldFormat = 'number' | 'currency' | 'date';
 export type InfoFieldSize = 'default' | 'lg';
@@ -103,27 +102,4 @@ declare global {
         'u-info-field': InfoField;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-info-field': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                label?: string;
-                /** 클래스 필드와 동일하게 `unknown` — 렌더 로직이 `String(value)`/포맷터로 무엇이
-                 *  오든 처리하므로 `null`·숫자를 그대로 넘길 수 있다(위 클래스 필드 JSDoc 참조). */
-                value?: unknown;
-                blank?: string;
-                numeric?: boolean;
-                format?: InfoFieldFormat;
-                currency?: string;
-                unit?: string;
-                size?: InfoFieldSize;
-                trend?: InfoFieldTrend;
-                /** 프로퍼티는 `trendLabel`이지만 Lit 기본 속성명 규칙(소문자화, kebab
-                 *  아님)상 실제 HTML 속성명은 `trendlabel`이다. */
-                trendlabel?: string;
-                tone?: InfoFieldTone;
-            };
-        }
-    }
-}
 export {};

package/dist/components/InfoSection.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'grid';
 /**
  * 정보 섹션 — `u-info-field` 들의 반응형 그리드.
@@ -29,13 +28,4 @@ declare global {
         'u-info-section': InfoSection;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-info-section': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                min?: number | string;
-            };
-        }
-    }
-}
 export {};

package/dist/components/MasterDetailLayout.d.ts

@@ -1,6 +1,5 @@
 import { PropertyValues } from 'lit';
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'master' | 'divider' | 'detail' | 'detail-close';
 /**
  * master›detail 반응형 split-pane 셸.
@@ -92,15 +91,4 @@ declare global {
         'u-master-detail-layout': MasterDetailLayout;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-master-detail-layout': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                'master-size'?: string;
-                'overlay-breakpoint'?: number | string;
-                locale?: string;
-            };
-        }
-    }
-}
 export {};

package/dist/components/PageHeader.d.ts

@@ -1,5 +1,4 @@
 import { StyledElement } from '../internals/StyledElement.js';
-import { default as React } from 'react';
 type ElementParts = 'host' | 'back' | 'heading' | 'eyebrow' | 'title' | 'subtitle' | 'status' | 'actions';
 /**
  * 페이지 헤더 — 모든 LOB 화면 최상단의 같은 골격.
@@ -60,18 +59,4 @@ declare global {
         'u-page-header': PageHeader;
     }
 }
-declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'u-page-header': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                title?: string;
-                subtitle?: string;
-                eyebrow?: string;
-                back?: string;
-                'back-label'?: string;
-                locale?: string;
-            };
-        }
-    }
-}
 export {};

package/dist/layouts/SidebarLayout.js

@@ -30,23 +30,40 @@ function E(e) {
 	let n = e.getAttribute("role");
 	return n === "textbox" || n === "searchbox" || n === "combobox" || n === "spinbutton";
 }
-function D(e) {
+var D = /* @__PURE__ */ new Set([
+	"button",
+	"link",
+	"checkbox",
+	"switch",
+	"radio",
+	"menuitem",
+	"menuitemcheckbox",
+	"menuitemradio",
+	"option",
+	"tab",
+	"treeitem"
+]);
+function O(e) {
+	let t = e.tagName;
+	return t === "BUTTON" || t === "SUMMARY" || t === "A" && e.hasAttribute("href") ? !0 : D.has(e.getAttribute("role") ?? "");
+}
+function k(e) {
 	let t = getComputedStyle(e);
 	return (t.overflowY === "auto" || t.overflowY === "scroll") && e.scrollHeight > e.clientHeight;
 }
-function O(e, t) {
+function A(e, t) {
 	for (let n of e) if (n instanceof HTMLElement) {
-		if (D(n)) return n === t;
+		if (k(n)) return n === t;
 		if (n === t) break;
 	}
 	return !0;
 }
-function k() {
+function j() {
 	let e = document.activeElement;
 	for (; e?.shadowRoot?.activeElement;) e = e.shadowRoot.activeElement;
 	return e;
 }
-function A(e, t) {
+function M(e, t) {
 	let n = t;
 	for (; n;) {
 		if (n === e) return !0;
@@ -54,7 +71,7 @@ function A(e, t) {
 	}
 	return !1;
 }
-var j = class extends i {
+var N = class extends i {
 	static {
 		C = this;
 	}
@@ -85,7 +102,7 @@ var j = class extends i {
 		}, this.handleOverlaySlotChange = (e) => {
 			let t = o(e.target);
 			if (t && !this.hasOverlay) {
-				let e = k();
+				let e = j();
 				this.overlayTrigger = e && e !== document.body ? e : null;
 			}
 			this.hasOverlay = t;
@@ -97,10 +114,11 @@ var j = class extends i {
 		}, this.handleOverlayClose = () => {
 			this.fire("overlay-close", { cancelable: !1 });
 		}, this._handleMainKeydown = (e) => {
+			if (e.defaultPrevented) return;
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && E(t)) return;
+			if (t instanceof HTMLElement && E(t) || e.key === " " && t instanceof HTMLElement && O(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
-			if (!n || !O(e.composedPath(), n)) return;
+			if (!n || !A(e.composedPath(), n)) return;
 			let r = n.clientHeight;
 			switch (e.key) {
 				case " ":
@@ -350,14 +368,14 @@ var j = class extends i {
 	async focusRoute(e) {
 		let t = this.routeContent();
 		if (await Promise.all(t.map((e) => e.updateComplete)), this.hasOverlay || !e.isConnected) return;
-		let n = k();
-		n && t.some((e) => A(e, n)) || this.focusContentStart(t, e);
+		let n = j();
+		n && t.some((e) => M(e, n)) || this.focusContentStart(t, e);
 	}
 	focusContentStart(e, t) {
 		let n = b(e, "[autofocus]", y);
 		n?.focus();
-		let r = k();
-		n && r && A(n, r) || t.focus({ preventScroll: !0 });
+		let r = j();
+		n && r && M(n, r) || t.focus({ preventScroll: !0 });
 	}
 	overlayPanels() {
 		return (this.shadowRoot?.querySelector("slot[name=\"overlay\"]"))?.assignedElements({ flatten: !0 }) ?? [];
@@ -365,19 +383,19 @@ var j = class extends i {
 	async focusOverlay() {
 		let e = this.overlayPanels();
 		if (await Promise.all(e.map((e) => e.updateComplete)), !this.hasOverlay) return;
-		let t = k();
-		t && e.some((e) => A(e, t)) || (b(e, "[autofocus]", y) ?? b(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", y) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
+		let t = j();
+		t && e.some((e) => M(e, t)) || (b(e, "[autofocus]", y) ?? b(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", y) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
 	}
 	restoreOverlayFocus() {
 		let e = this.overlayTrigger;
 		this.overlayTrigger = null;
-		let t = k();
+		let t = j();
 		t && t !== document.body || (e?.isConnected ? e.focus() : this.mainElement?.focus({ preventScroll: !0 }));
 	}
 };
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], j.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], j.prototype, "config", void 0), r([f({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], j.prototype, "counts", void 0), r([f({ type: String }), n("design:type", Object)], j.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], j.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], j.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], j.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], j.prototype, "context", void 0), j = C = r([d("u-sidebar-layout")], j);
+}), n("design:type", Object)], N.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], N.prototype, "config", void 0), r([f({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], N.prototype, "counts", void 0), r([f({ type: String }), n("design:type", Object)], N.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], N.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], N.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], N.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], N.prototype, "context", void 0), N = C = r([d("u-sidebar-layout")], N);
 //#endregion
-export { j as SidebarLayout };
+export { N as SidebarLayout };

package/dist/react.d.ts

@@ -2,6 +2,8 @@ import { default as React } from 'react';
 import { EventName } from '@lit/react';
 import { SidebarLayout as SidebarLayoutElement } from './layouts/SidebarLayout.js';
 import { Wizard as WizardElement, WizardStepChangeDetail } from './components/Wizard.js';
+import { GroupBoxLevel } from './components/GroupBox.js';
+import { InfoFieldFormat, InfoFieldSize, InfoFieldTrend, InfoFieldTone } from './components/InfoField.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';
 export type { ScreenSize, ScreenObserverConfig, ScreenResizeEvent } from './internals/ScreenObserver.js';
 /**
@@ -27,3 +29,59 @@ export type WizardProps = React.ComponentProps<typeof Wizard>;
 export type { SidebarLayoutElement, WizardElement };
 export type { SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarHtmlConfig, } from './layouts/SidebarLayout.types.js';
 export type { WizardStep, WizardStepState, WizardStepChangeDetail } from './components/Wizard.js';
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'u-action-bar': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                sticky?: boolean;
+            };
+            'u-empty-state': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                variant?: 'no-data' | 'no-results';
+                title?: string;
+                description?: string;
+                locale?: string;
+            };
+            'u-group-box': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                title?: string;
+                divider?: boolean;
+                flush?: boolean;
+                level?: GroupBoxLevel;
+                meta?: string;
+                description?: string;
+            };
+            'u-info-field': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                label?: string;
+                /** 클래스 필드와 동일하게 `unknown` — 렌더 로직이 `String(value)`/포맷터로 무엇이
+                 *  오든 처리하므로 `null`·숫자를 그대로 넘길 수 있다(`InfoField.value` 의 JSDoc 참조). */
+                value?: unknown;
+                blank?: string;
+                numeric?: boolean;
+                format?: InfoFieldFormat;
+                currency?: string;
+                unit?: string;
+                size?: InfoFieldSize;
+                trend?: InfoFieldTrend;
+                /** 프로퍼티는 `trendLabel`이지만 Lit 기본 속성명 규칙(소문자화, kebab
+                 *  아님)상 실제 HTML 속성명은 `trendlabel`이다. */
+                trendlabel?: string;
+                tone?: InfoFieldTone;
+            };
+            'u-info-section': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                min?: number | string;
+            };
+            'u-master-detail-layout': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                'master-size'?: string;
+                'overlay-breakpoint'?: number | string;
+                locale?: string;
+            };
+            'u-page-header': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+                title?: string;
+                subtitle?: string;
+                eyebrow?: string;
+                back?: string;
+                'back-label'?: string;
+                locale?: string;
+            };
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -60,7 +60,7 @@
     "test:react-types": "tsc -p tsconfig.react-smoke.json"
   },
   "dependencies": {
-    "@iyulab/router": "^0.19.0",
+    "@iyulab/router": "^0.19.1",
     "i18next": "^26.3.6",
     "lit": "^3.3.3"
   },

package/skills/modern-app/SKILL.md

@@ -37,8 +37,8 @@ await app.load({
     logo: { src: '/assets/logo.svg', alt: 'My App' },
     title: 'My App',
     main: [
-      { type: 'link', icon: 'home', label: 'Home',     href: '/' },
-      { type: 'link', icon: 'users', label: 'Users',   href: '/users' },
+      { type: 'link', icon: 'home',  lib: 'tabler', label: 'Home',  href: '/' },
+      { type: 'link', icon: 'users', lib: 'tabler', label: 'Users', href: '/users' },
     ],
   },
   routes: [
@@ -52,6 +52,10 @@ await app.load({
 });
 ```
 
+Menu `icon` names resolve through `<u-icon>`: with `lib` from that library (`tabler`, `heroicons`, `lucide`,
+`bootstrap` are pre-registered, CDN-fetched), without `lib` from the app's own `/assets/icons/<name>.svg`.
+An unresolved name draws a neutral placeholder — every item showing the same icon means the set is missing.
+
 To tear down the app:
 
 ```typescript
@@ -70,6 +74,9 @@ app.router?.context;             // current RouteContext
 app.router?.routes;              // registered routes
 ```
 
+On a static host that serves one document, `app.load({ routerMode: 'hash' })` keeps the route after `#`
+(`/#/users/42`); links and `app.navigate()` follow the mode.
+
 ---
 
 ## Theme