@iyulab/modern-app 0.34.2 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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/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.2",
+  "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