@iyulab/modern-app 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -1,99 +1,113 @@
 # Changelog
 
-## 0.3.3 (2026-04-01)
+## [0.3.5] - 2026-04-07
 
-### Fixes
-- **Sidebar 컴포넌트 customElement 등록명 수정**: `sidebar-*` → `u-sidebar-*` 접두사 추가
-  - `SidebarButton`, `SidebarGroup`, `SidebarLink`, `SidebarSection` 4개 컴포넌트
-  - `SidebarLayout` 템플릿에서 `u-sidebar-*`로 참조하지만 등록은 `sidebar-*`로 되어 있어 렌더링 안 되던 버그 수정
+### Changed
+- Updated dependencies: `@iyulab/components` ^1.0.1 → ^1.0.3, `@iyulab/router` ^0.7.4 → ^0.9.1
 
-## 0.3.2 (2026-04-01)
+## [0.3.4] - 2026-04-01
 
-### Breaking Changes
-- **`@iyulab/components` major upgrade**: `^0.4.0` → `^1.0.0`
-  - `Notifier` → `Toast` API migration
-  - `AlertType` → `AlertStatus`, `ScreenPosition` → `ToastPosition` type rename
-  - `IconRegistry` import path: `utilities/IconRegistry.js` → `utilities/icons.js`
-  - Component import style: `.component.js` → side-effect import (`UIcon.js`, `UButton.js`, etc.)
+### Added
+- Progress bar fade-in/out with CSS transition tied to `route-begin` and `route-done` events
+- Progress bar error state (red) on `route-error` with auto-dismiss
+- `docs/` topic guides and `skills/modern-app/` agent skill package
 
-### Refactor
-- **Component registration migration**: Removed `static dependencies` pattern → `@customElement` decorator + side-effect import
-- **Simplified Toast API**: Removed `private notify()` method from `App` class, each notification method now calls `Toast.notice()`, etc. directly
+### Changed
+- Rewrote `README.md` with accurate API references and links to docs and skills
 
-### Fixes
-- Changed `updated()` → `willUpdate()` in `SidebarLayout` to resolve update-in-update anti-pattern
-- Switched `SidebarLayout` icon library from inline `sidebar-app` to `bootstrap`, removed inline SVG registration code
+## [0.3.3] - 2026-04-01
 
-### Dependencies
-- `@iyulab/components` ^0.4.0 → ^1.0.0
-- `i18next` ^25.8.13 → ^25.10.10
-- `vite` ^7.3.1 → ^8.0.3
-- `@types/node` ^25.3.2 → ^25.5.0
+### Fixed
+- Fixed missing `u-` prefix in `customElement` registration for `SidebarButton`, `SidebarGroup`, `SidebarLink`, and `SidebarSection` — components were referenced as `u-sidebar-*` in templates but registered as `sidebar-*`, causing them not to render
 
-## 0.3.1 (2026-03-05)
+## [0.3.2] - 2026-04-01
 
-### Breaking Changes
-- **Slot-based Outlet structure**: Replaced `<u-outlet>` inside `SidebarLayout` with `<slot>`, and moved `<u-outlet>` to Light DOM in `App`. This allows external CSS to apply correctly during React routing
+### Changed
+- **Breaking:** Upgraded `@iyulab/components` from `^0.4.0` to `^1.0.0`:
+  - `Notifier` → `Toast` API migration
+  - `AlertType` → `AlertStatus`, `ScreenPosition` → `ToastPosition` type renames
+  - `IconRegistry` import path: `utilities/IconRegistry.js` → `utilities/icons.js`
+  - Component import style: `.component.js` → side-effect import (e.g. `UIcon.js`, `UButton.js`)
+- Removed `static dependencies` pattern — switched to `@customElement` decorator with side-effect imports
+- Simplified Toast API: each notification method now calls `Toast.notice()` etc. directly; removed private `notify()` from `App` class
+- Updated dependencies: `i18next` ^25.8.13 → ^25.10.10, `vite` ^7.3.1 → ^8.0.3, `@types/node` ^25.3.2 → ^25.5.0
 
-### Changes
-- **BaseElement → UElement migration**: Changed base class of all components from `BaseElement` to `UElement`
-- **SidebarLinkConfig**: Changed `type` property from optional to required
-- **Fixed import paths**: Corrected casing for `Theme.js`, `Notifier.js`, etc.
+### Fixed
+- Changed `updated()` → `willUpdate()` in `SidebarLayout` to resolve update-in-update anti-pattern
+- Switched `SidebarLayout` icon library from inline `sidebar-app` to `bootstrap`; removed inline SVG registration
 
-### Fixes
+## [0.3.1] - 2026-03-05
+
+### Changed
+- **Breaking:** Replaced `<u-outlet>` inside `SidebarLayout` with `<slot>`; moved `<u-outlet>` to Light DOM in `App` to allow external CSS during React routing
+- Migrated base class of all components from `BaseElement` to `UElement`
+- `SidebarLinkConfig.type` changed from optional to required
+- Corrected import path casing for `Theme.js`, `Notifier.js`, etc.
+- Updated dependencies: `@iyulab/components` ^0.2.0 → ^0.4.0, `@iyulab/router` ^0.6.2 → ^0.7.2, `i18next` ^25.8.0 → ^25.8.13, `@types/node` ^25.0.9 → ^25.3.2
+
+### Fixed
 - Removed duplicate `color` property in `SidebarButton.styles.ts`
 - Cleaned up unused callback parameters in `repeat` directive
 
-### Dependencies
-- `@iyulab/components` ^0.2.0 → ^0.4.0
-- `@iyulab/router` ^0.6.2 → ^0.7.2
-- `i18next` ^25.8.0 → ^25.8.13
-- `@types/node` ^25.0.9 → ^25.3.2
-
-## 0.3.0 (2026-01-21)
-
-### Breaking Changes
-- **Configuration Updates**:
-  - Renamed `localization` to `i18n`
-  - Renamed `layout.menu` to `layout.main` 
-  - Changed `logo` type to string (icon name)
-  - Added `title` property for app title
-  - Added `iconBasepath` option
-- **Mobile layout support**: New mobile states (`mobile`, `mobile-open`) with dedicated mobile header
-
-### Removals
-- Removed `SidebarLogo` component: Logo is now rendered using `u-icon` component
-- Removed `observables.ts`: Replaced MobX observables with native `ScreenObserver` class
-- Removed `AppTypes.ts`: Type definitions moved to their respective modules
-
-### Improvements
-- Improved responsive behavior with screen size observer
-- Added route context tracking and active link highlighting
-- Improved color scheme and typography
-- Enhanced transition animations
-- Cleaner layout spacing and gaps
-- Improved event handling for route changes and screen resizing
-- Enhanced pattern matching for active link detection
-
-## 0.2.5 (2026-01-06)
+## [0.3.0] - 2026-01-21
+
+### Added
+- Mobile layout support with new states (`mobile`, `mobile-open`) and dedicated mobile header
+- Route context tracking and active link highlighting
+- `ScreenObserver` class replacing MobX observables for responsive behavior
+- `title` and `iconBasepath` properties in app configuration
+
+### Changed
+- **Breaking:** `localization` config option renamed to `i18n`
+- **Breaking:** `layout.menu` renamed to `layout.main`
+- **Breaking:** `logo` type changed to string (icon name)
+- Type definitions moved from `AppTypes.ts` to their respective modules
+- Improved color scheme, typography, transition animations, layout spacing, and event handling
+
+### Removed
+- Removed `SidebarLogo` component — logo now rendered via `u-icon`
+- Removed `observables.ts` (replaced by `ScreenObserver`)
+- Removed `AppTypes.ts`
+
+## [0.2.5] - 2026-01-06
+
+### Changed
 - Updated `@iyulab/components` to v0.1.11
 
-## 0.2.4 (2025-12-19)
-- fix import path, modified correct case-sensitive paths
+## [0.2.4] - 2025-12-19
+
+### Fixed
+- Fixed case-sensitive import paths
+
+## [0.2.3] - 2025-12-19
+
+### Added
+- `root` option in `AppConfig` to set the application root element
+
+### Changed
+- Updated `@iyulab/components` to v0.1.10
+
+## [0.2.2] - 2025-11-17
+
+### Added
+- `fallback` config option in `AppConfig`
+
+### Changed
+- Improved `route-progress` handling in layout component
+
+## [0.2.1] - 2025-11-13
+
+### Changed
+- `progress` property changed from a value to a function on the `app` instance
+- `locales` option renamed to `localization` in `AppConfig`
 
-## 0.2.3 (2025-12-19)
-- added `root` option in `AppConfig` type to set application root element
-- update `@iyulab/components` to v0.1.10
+### Fixed
+- Fixed component and sidebar style issues
 
-## 0.2.2 (2025-11-17)
-- added `fallback` config in `AppConfig` type
-- improved route-progress handling in layout component
+### Removed
+- Removed `theme` setter property from `app` instance
 
-## 0.2.1 (2025-11-13)
-- Fixed few component and sidebar styles
-- removed `theme` setter property in `app` instance
-- changed `progress` property to function in `app` instance
-- changed name `locales` option to `localization` option in `AppConfig` type
+## [0.2.0] - 2025-11-12
 
-## 0.2.0 (2025-11-12)
-- Initial library version release
+### Added
+- Initial release

package/README.md

@@ -1,8 +1,6 @@
-# Modern App
+# @iyulab/modern-app
 
-A modern web application framework by iyulab, built on React and Lit Element.
-
-For complete examples and documentation, visit our demo site: [https://modern-app.iyulab.com](https://modern-app.iyulab.com)
+A client-side SPA framework built on [Lit Element](https://lit.dev/) by iyulab. It bundles routing, a responsive sidebar layout, theme management, toast notifications, and i18n into a single `app` singleton.
 
 ## Installation
 
@@ -10,167 +8,119 @@ For complete examples and documentation, visit our demo site: [https://modern-ap
 npm install @iyulab/modern-app
 ```
 
-## Architecture
-
-`@iyulab/modern-app` is a **client-side SPA framework** built on Lit Element. It is designed for:
-
-✅ **Suitable for:**
-- Single Page Applications (SPA)
-- Admin dashboards and internal tools
-- Progressive Web Apps (PWA)
-- Projects where SEO is not a primary concern
-
-❌ **Not suitable for:**
-- Server-Side Rendering (SSR) frameworks (Next.js, Nuxt, SvelteKit, etc.)
-- Static Site Generation (SSG)
-- SEO-critical public-facing pages
-- Projects requiring initial HTML content for search engines
+## When to use it
 
-This is by design — Lit components render on the client side. If you need SSR capabilities, consider using Lit's experimental SSR support separately or choose a framework designed for SSR from the start.
+| ✅ Good fit | ❌ Not a good fit |
+|-------------|-----------------|
+| Single Page Applications (SPA) | SSR frameworks (Next.js, Nuxt, SvelteKit) |
+| Admin dashboards and internal tools | Static Site Generation (SSG) |
+| Progressive Web Apps (PWA) | SEO-critical public-facing pages |
 
 ## Quick Start
 
 ```typescript
 import { app } from '@iyulab/modern-app';
+import { html } from 'lit';
 
 await app.load({
   basepath: '/',
   layout: {
     type: 'sidebar',
-    // ...layout configuration
+    logo: '/assets/logo.svg',
+    title: 'My App',
+    main: [
+      { type: 'link', icon: 'home',  label: 'Home',  href: '/' },
+      { type: 'link', icon: 'users', label: 'Users', href: '/users' },
+    ],
   },
   routes: [
-    { index: true, render: () => html`<home-page></home-page>` },
-    { path: 'about', render: () => html`<about-page></about-page>` },
+    { index: true,       render: () => html`<home-page></home-page>` },
+    { path: 'users',     render: () => html`<users-page></users-page>` },
+    { path: 'users/:id', render: (ctx) => html`<user-detail .userId=${ctx.params.id}></user-detail>` },
   ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
+  },
+  theme: { default: 'system' },
 });
 ```
 
-## API Reference
+## Skills Usage
 
-### Navigation
+AI agent skills for this package are located in `skills/modern-app/`. Install them with `npx skills`:
 
-```typescript
-// Navigate to a path
-app.navigate('/path');
-
-// Access router instance
-app.router?.go('/path');
-app.router?.basepath;   // Get base path
-app.router?.routes;     // Get registered routes
-app.router?.context;    // Get current route context
+**From GitHub:**
+```bash
+npx skills add iyulab/node-modern-app
 ```
 
-### Theme Management
-
-```typescript
-// Get current theme
-app.theme.get();  // Returns: 'system' | 'light' | 'dark' | undefined
-
-// Set theme
-app.theme.set('dark');   // 'system' | 'light' | 'dark'
-
-// Check initialization status
-app.theme.isInitialized;
+**From local `node_modules`:**
+```bash
+npx skills add ./node_modules/@iyulab/modern-app
 ```
 
-### Notifications
-
-```typescript
-// Display notifications (returns Promise<void>)
-await app.notice('Notice message');
-await app.info('Info message');
-await app.success('Success message');
-await app.warning('Warning message');
-await app.error('Error message');
-
-// With options
-await app.success('Saved!', {
-  title: 'Success',
-  duration: 5000,  // milliseconds (default: 3000)
-  position: 'top-right'  // 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
-});
-```
+## Core API
 
-### Localization
+### Navigation
 
 ```typescript
-// Access i18next instance
-app.localizer;  // i18next instance
-
-// Usage with lit-i18n
-import { translate } from 'lit-i18n';
-html`<p>${translate('namespace::key')}</p>`;
+app.navigate('/users/42');     // push a route
+app.router?.go('/users/42');   // via router instance
+app.router?.context;           // current RouteContext
 ```
 
-## Configuration
-
-### AppConfig
+### Theme
 
 ```typescript
-interface AppConfig {
-  root?: Element;              // Root element (default: document.body)
-  basepath?: string;           // Base path for routing (default: '/')
-  routes: RouteConfig[];       // Route definitions
-  fallback?: FallbackConfig;   // Error fallback route
-  theme?: ThemeInitOptions;    // Theme configuration
-  localization?: i18next.InitOptions;  // i18next options
-  layout: LayoutConfig;        // Layout configuration
-}
+app.theme.get();         // 'system' | 'light' | 'dark' | undefined
+app.theme.set('dark');
+app.theme.isInitialized; // boolean
 ```
 
-### Theme Options
+### Notifications
 
 ```typescript
-interface ThemeInitOptions {
-  default?: 'system' | 'light' | 'dark';  // Default theme
-  debug?: boolean;                         // Enable debug logging
-  store?: false | {                        // Persist theme preference
-    type: 'cookie' | 'localStorage' | 'sessionStorage';
-    prefix?: string;
-  };
-  useBuiltIn?: boolean;  // Use built-in styles (default: true)
-}
+await app.success('Saved!', { title: 'Done', duration: 4000, position: 'top-right' });
+await app.error('Something went wrong');
+await app.info('Info message');
+await app.warning('Double-check this');
+await app.notice('Neutral notice');
 ```
 
-### Layout Configuration (Sidebar)
+### Localization (i18next)
 
 ```typescript
-interface SidebarLayoutConfig {
-  type: 'sidebar';
-  breakpoints?: [number, number];  // [small, medium] (default: [768, 1024])
-  logo?: {
-    type: 'icon' | 'image';
-    icon?: string;
-    src?: string;
-    label?: string;
-    onClick?: () => void;
-  };
-  menu?: MenuItem[];     // Navigation menu items
-  footer?: FooterItem[]; // Footer buttons/items
-}
-```
+// Pass i18next plugins and InitOptions
+await app.load({
+  // ...
+  i18n: {
+    plugins: [i18nextHttpBackend],
+    lng: 'en',
+    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
+  },
+});
 
-### Route Configuration
+// Access i18next
+app.i18n.t('common::greeting');
+app.i18n.changeLanguage('ko');
 
-```typescript
-interface RouteConfig {
-  index?: boolean;           // Index route
-  path?: string;             // Route path (supports :param patterns)
-  title?: string;            // Document title
-  force?: boolean;           // Force re-render
-  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
-}
-
-interface RouteContext {
-  href: string;              // Full URL
-  pathname: string;          // Path portion
-  basepath: string;          // Base path
-  params: Record<string, string>;  // URL parameters
-  progress: (value: number) => void;  // Progress callback (0-100)
-}
+// Reactive translations in Lit templates
+import { translate } from 'lit-i18n';
+html`<p>${translate('common::greeting')}</p>`;
 ```
 
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [getting-started.md](./docs/getting-started.md) | Bootstrap, architecture, entry point setup |
+| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress |
+| [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
+| [theme.md](./docs/theme.md) | Theme init, runtime switching, CSS tokens |
+| [notifications.md](./docs/notifications.md) | Toast methods and options |
+| [i18n.md](./docs/i18n.md) | i18next setup, plugins, lit-i18n usage |
+| [configuration.md](./docs/configuration.md) | Full TypeScript interface reference |
+
 ## License
 
 MIT

package/dist/_virtual/{_@oxc-project_runtime@0.122.0 → _@oxc-project_runtime@0.124.0}/helpers/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.122.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.124.0/helpers/decorate.js
 function e(e, t, n, r) {
 	var i = arguments.length, a = i < 3 ? t : r === null ? r = Object.getOwnPropertyDescriptor(t, n) : r, o;
 	if (typeof Reflect == "object" && typeof Reflect.decorate == "function") a = Reflect.decorate(e, t, n, r);

package/dist/_virtual/{_@oxc-project_runtime@0.122.0 → _@oxc-project_runtime@0.124.0}/helpers/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.122.0/helpers/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.124.0/helpers/decorateMetadata.js
 function e(e, t) {
 	if (typeof Reflect == "object" && typeof Reflect.metadata == "function") return Reflect.metadata(e, t);
 }

package/dist/components/SidebarButton.js

@@ -1,5 +1,5 @@
-import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarButton.styles.js";
 import { html as i } from "lit";

package/dist/components/SidebarGroup.js

@@ -1,5 +1,5 @@
-import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { SidebarLink as r } from "./SidebarLink.js";
 import { styles as i } from "./SidebarGroup.styles.js";

package/dist/components/SidebarLink.js

@@ -1,5 +1,5 @@
-import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarLink.styles.js";
 import { html as i } from "lit";

package/dist/components/SidebarSection.js

@@ -1,5 +1,5 @@
-import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarSection.styles.js";
 import { html as i } from "lit";

package/dist/internals/StyledElement.js

@@ -1,5 +1,5 @@
-import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as e } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { property as n } from "lit/decorators.js";
 import { UElement as r } from "@iyulab/components/dist/components/UElement.js";
 //#region src/internals/StyledElement.ts

package/dist/layouts/SidebarLayout.d.ts

@@ -49,6 +49,8 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private handleRouteProgress;
     /** 라우트 변경 완료 핸들러 */
     private handleRouteDone;
+    /** 라우트 에러 핸들러 */
+    private handleRouteError;
     /** 화면 크기 변경에 따른 사이드바 상태 업데이트 */
     private handleScreenResize;
 }

package/dist/layouts/SidebarLayout.js

@@ -1,6 +1,6 @@
 import { app as e } from "../App.js";
-import { __decorateMetadata as t } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorateMetadata.js";
-import { __decorate as n } from "../_virtual/_@oxc-project_runtime@0.122.0/helpers/decorate.js";
+import { __decorateMetadata as t } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorateMetadata.js";
+import { __decorate as n } from "../_virtual/_@oxc-project_runtime@0.124.0/helpers/decorate.js";
 import { StyledElement as r } from "../internals/StyledElement.js";
 import "../components/SidebarSection.js";
 import "../components/SidebarLink.js";
@@ -25,11 +25,17 @@ var m, h = class extends r {
 		}, this.handleBackdropClick = () => {
 			this.state = "slim";
 		}, this.handleRouteBegin = (e) => {
-			this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.context = e.context;
+			this.progressBarEl.setAttribute("visible", ""), this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.context = e.context;
 		}, this.handleRouteProgress = (e) => {
 			this.progressBarEl.value = e.progress;
 		}, this.handleRouteDone = (e) => {
-			this.progressBarEl.value = 100;
+			this.progressBarEl.value = 100, setTimeout(() => {
+				this.progressBarEl.removeAttribute("visible");
+			}, 300);
+		}, this.handleRouteError = (e) => {
+			this.progressBarEl.setAttribute("error", ""), this.progressBarEl.value = 100, setTimeout(() => {
+				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.removeAttribute("error");
+			}, 300);
 		}, this.handleScreenResize = (e) => {
 			let t = e.detail.size;
 			t === "large" ? this.state = "default" : t === "medium" ? this.state = "slim" : t === "small" ? this.state = "mobile" : console.warn("Unknown screen size:", t);
@@ -39,10 +45,10 @@ var m, h = class extends r {
 		this.styles = [super.styles, i];
 	}
 	connectedCallback() {
-		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("screen-resize", this.handleScreenResize);
+		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);
 	}
 	disconnectedCallback() {
-		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("screen-resize", this.handleScreenResize), super.disconnectedCallback();
+		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), super.disconnectedCallback();
 	}
 	willUpdate(e) {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);

package/dist/layouts/SidebarLayout.styles.js

@@ -151,14 +151,25 @@ var t = e`
   }
 
   .main u-progress-bar {
+    --progress-bar-height: 4px;
+    --progres-bar-track-color: transparent;
+    
     position: absolute;
     z-index: 100;
     top: 0;
     left: 0;
     right: 0;
-    height: 4px;
-    border-radius: 0;
-    background-color: transparent;
+    opacity: 0;
+    transform: translateY(-4px);
+    transition: opacity 0.3s ease, transform 0.3s ease;
+    pointer-events: none;
+  }
+  .main u-progress-bar[visible] {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  .main u-progress-bar[error] {
+    --progress-bar-color: var(--u-red-500);
   }
 
   /* Backdrop for modal mode */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -15,6 +15,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
     "CHANGELOG.md",
@@ -37,15 +38,15 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@iyulab/components": "^1.0.0",
-    "@iyulab/router": "^0.7.4",
-    "i18next": "^25.10.10",
+    "@iyulab/components": "^1.0.3",
+    "@iyulab/router": "^0.9.1",
+    "i18next": "^26.0.6",
     "lit": "^3.3.2"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "typescript": "^5.9.3",
-    "vite": "^8.0.3",
+    "vite": "^8.0.8",
     "vite-plugin-dts": "^4.5.4"
   }
 }

package/skills/modern-app/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: modern-app
+description: Client-side SPA framework built on Lit Element. Bootstraps an application with sidebar layout, client-side routing, theme management, toast notifications, and i18n (i18next). Use when working with the @iyulab/modern-app package — setting up a new app, configuring routes, adding navigation menu items, managing theme, showing toasts, or wiring up localization.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.3.4"
+compatibility: Designed for Lit Element / TypeScript projects. Requires @iyulab/modern-app.
+---
+
+# @iyulab/modern-app
+
+A client-side SPA framework built on Lit Element. Provides a single `app` singleton that wires together routing, layout, theme, notifications, and i18n.
+
+> **Suitable for:** SPAs, admin dashboards, internal tools, PWAs.  
+> **Not suitable for:** SSR (Next.js, Nuxt, SvelteKit), SSG, SEO-critical pages.
+
+## Installation
+
+```bash
+npm install @iyulab/modern-app
+```
+
+---
+
+## Bootstrap
+
+Call `app.load()` once at the entry point. All options are in [`AppConfig`](./references/api.md#appconfig).
+
+```typescript
+import { app } from '@iyulab/modern-app';
+import { html } from 'lit';
+
+await app.load({
+  basepath: '/',
+  layout: {
+    type: 'sidebar',
+    logo: '/assets/logo.svg',
+    title: 'My App',
+    main: [
+      { type: 'link', icon: 'home', label: 'Home',     href: '/' },
+      { type: 'link', icon: 'users', label: 'Users',   href: '/users' },
+    ],
+  },
+  routes: [
+    { index: true,       render: () => html`<home-page></home-page>` },
+    { path: 'users',     render: () => html`<users-page></users-page>` },
+    { path: 'users/:id', render: (ctx) => html`<user-detail .userId=${ctx.params.id}></user-detail>` },
+  ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
+  },
+});
+```
+
+To tear down the app:
+
+```typescript
+app.unload();
+```
+
+---
+
+## Navigation
+
+```typescript
+app.navigate('/users/42');       // push route
+app.router?.go('/users/42');     // same via router instance
+app.router?.basepath;            // base path string
+app.router?.context;             // current RouteContext
+app.router?.routes;              // registered routes
+```
+
+---
+
+## Theme
+
+```typescript
+app.theme.get();          // 'system' | 'light' | 'dark' | undefined
+app.theme.set('dark');    // 'system' | 'light' | 'dark'
+app.theme.isInitialized;  // boolean
+```
+
+Theme `store` options persist the preference across sessions:
+
+```typescript
+theme: {
+  default: 'system',
+  store: { type: 'localStorage', prefix: 'myapp' },
+  useBuiltIn: true,
+}
+```
+
+---
+
+## Notifications (Toast)
+
+All methods return `Promise<void>`.
+
+```typescript
+await app.notice('A general notice');
+await app.info('Loaded successfully');
+await app.success('Saved!', { title: 'Done', duration: 4000, position: 'top-right' });
+await app.warning('Check your input');
+await app.error('Something went wrong');
+```
+
+`position` values: `'top-right'` | `'top-left'` | `'bottom-right'` | `'bottom-left'`  
+`duration` default: `3000` ms
+
+---
+
+## Localization (i18next)
+
+Pass standard i18next `InitOptions` plus an optional `plugins` array.
+
+```typescript
+import i18nextHttpBackend from 'i18next-http-backend';
+
+await app.load({
+  // ...
+  i18n: {
+    plugins: [i18nextHttpBackend],
+    lng: 'en',
+    fallbackLng: 'en',
+    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
+  },
+});
+
+// Access i18next instance
+app.i18n.t('namespace::key');
+```
+
+Use in Lit templates with `lit-i18n`:
+
+```typescript
+import { translate } from 'lit-i18n';
+html`<p>${translate('namespace::greeting')}</p>`;
+```
+
+---
+
+## Sidebar Layout
+
+Full configuration reference: [references/layout.md](./references/layout.md)
+
+### Menu item types
+
+| type | Description |
+|------|-------------|
+| `'link'` | Single navigation link with optional icon |
+| `'group'` | Collapsible group of links |
+| `'section'` | Labelled section grouping links and groups |
+| `'button'` | Action button (non-navigation) |
+| `'html'` | Custom Lit template rendered inline |
+
+```typescript
+layout: {
+  type: 'sidebar',
+  logo: '/logo.svg',
+  title: 'App Name',
+  main: [
+    {
+      type: 'section',
+      title: 'Management',
+      items: [
+        { type: 'link',  icon: 'users', label: 'Users',    href: '/users' },
+        {
+          type: 'group', icon: 'settings', label: 'Settings',
+          items: [
+            { type: 'link', label: 'Profile',  href: '/settings/profile' },
+            { type: 'link', label: 'Security', href: '/settings/security' },
+          ],
+        },
+      ],
+    },
+  ],
+  footer: [
+    { type: 'button', icon: 'logout', label: 'Logout', onClick: () => signOut() },
+  ],
+}
+```
+
+### Responsive breakpoints
+
+```typescript
+layout: {
+  type: 'sidebar',
+  breakpoints: [768, 1024], // [tablet-min-px, desktop-min-px]
+  // ...
+}
+```
+
+Sidebar states: `'default'` | `'slim'` | `'modal'` | `'mobile'` | `'mobile-open'`
+
+---
+
+## Routes with progress
+
+```typescript
+{
+  path: 'dashboard',
+  title: 'Dashboard',
+  render: async (ctx) => {
+    ctx.progress(30);
+    const data = await fetchData();
+    ctx.progress(100);
+    return html`<dashboard-page .data=${data}></dashboard-page>`;
+  },
+}
+```
+
+`RouteContext` fields: `href`, `pathname`, `basepath`, `params`, `progress`
+
+---
+
+## Full `AppConfig` reference
+
+See [references/api.md](./references/api.md) for all TypeScript interfaces.

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

@@ -0,0 +1,179 @@
+# API Reference — @iyulab/modern-app
+
+## `AppConfig`
+
+```typescript
+interface AppConfig {
+  /** Root element to render into. Default: document.body */
+  root?: Element;
+
+  /** Base path for all routes. Default: '/' */
+  basepath?: string;
+
+  /** Base URL for icon assets. Default: '/assets/icons/' */
+  iconBasepath?: string;
+
+  /** Route definitions. */
+  routes?: RouteConfig[];
+
+  /** Fallback rendered on 404 or unhandled errors. */
+  fallback?: FallbackRouteConfig;
+
+  /** Layout configuration. Currently only 'sidebar' is supported. */
+  layout: LayoutConfig;
+
+  /** Theme initialization options. */
+  theme?: ThemeInitOptions;
+
+  /** i18next options plus optional plugins array. Omit to skip i18n. */
+  i18n?: I18nInitOptions;
+}
+```
+
+---
+
+## `LayoutConfig`
+
+```typescript
+type LayoutConfig = SidebarLayoutConfig & {
+  /** Responsive breakpoints [tablet-min, desktop-min] in px. Default: [768, 1024] */
+  breakpoints?: [number, number];
+};
+```
+
+---
+
+## `ThemeInitOptions`
+
+```typescript
+interface ThemeInitOptions {
+  /** Initial theme. Default: 'system' */
+  default?: 'system' | 'light' | 'dark';
+
+  /** Log theme decisions to console. */
+  debug?: boolean;
+
+  /**
+   * Persist the user's preference.
+   * Set to `false` to disable persistence.
+   * Default: localStorage with no prefix.
+   */
+  store?: false | {
+    type: 'cookie' | 'localStorage' | 'sessionStorage';
+    prefix?: string;
+  };
+
+  /** Apply built-in CSS custom properties. Default: true */
+  useBuiltIn?: boolean;
+}
+```
+
+---
+
+## `RouteConfig`
+
+```typescript
+interface RouteConfig {
+  /** Matches the root path (equivalent to `path: ''`). */
+  index?: boolean;
+
+  /** Path string. Supports `:param` segments. */
+  path?: string;
+
+  /** Sets `document.title` when the route activates. */
+  title?: string;
+
+  /** Force a re-render even if the path did not change. */
+  force?: boolean;
+
+  /** Render function. May be async. */
+  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
+}
+```
+
+---
+
+## `RouteContext`
+
+```typescript
+interface RouteContext {
+  /** Full URL string. */
+  href: string;
+
+  /** Pathname portion of the URL. */
+  pathname: string;
+
+  /** Configured basepath. */
+  basepath: string;
+
+  /** Named URL parameters extracted from the path pattern. */
+  params: Record<string, string>;
+
+  /**
+   * Report loading progress (0–100).
+   * Drives the progress bar shown in the layout header.
+   */
+  progress: (value: number) => void;
+}
+```
+
+---
+
+## `FallbackRouteConfig`
+
+```typescript
+interface FallbackRouteConfig {
+  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
+}
+```
+
+The fallback `RouteContext` will include an `error` property when triggered by
+a routing error.
+
+---
+
+## `I18nInitOptions`
+
+```typescript
+type I18nInitOptions = i18next.InitOptions & {
+  /** i18next plugins to register via i18next.use() before init. */
+  plugins?: (Module | NewableModule<Module> | Newable<Module>)[];
+};
+```
+
+---
+
+## `NotificationOptions`
+
+```typescript
+interface NotificationOptions {
+  title?: string;
+  duration?: number;   // milliseconds, default 3000
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+}
+```
+
+---
+
+## `app` singleton methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `load` | `(config: AppConfig) => Promise<void>` | Initialize and mount the application |
+| `unload` | `() => void` | Tear down layout, router, and observers |
+| `navigate` | `(path: string) => void` | Push a new route |
+| `notice` | `(msg, opts?) => Promise<void>` | Show a neutral toast |
+| `info` | `(msg, opts?) => Promise<void>` | Show an info toast |
+| `success` | `(msg, opts?) => Promise<void>` | Show a success toast |
+| `warning` | `(msg, opts?) => Promise<void>` | Show a warning toast |
+| `error` | `(msg, opts?) => Promise<void>` | Show an error toast |
+
+### `app` singleton properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `config` | `AppConfig \| undefined` | Current config passed to `load()` |
+| `router` | `Router \| undefined` | Underlying `@iyulab/router` instance |
+| `screen` | `ScreenSize \| undefined` | Current responsive screen size |
+| `theme` | `Theme` (static) | Theme utility (`get`, `set`, `isInitialized`) |
+| `i18n` | `i18next` | Raw i18next instance |

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

@@ -0,0 +1,204 @@
+# Sidebar Layout Reference — @iyulab/modern-app
+
+## `SidebarLayoutConfig`
+
+```typescript
+interface SidebarLayoutConfig {
+  type: 'sidebar';
+
+  /** URL or path to the logo image. */
+  logo?: string;
+
+  /** Application title displayed beside the logo. */
+  title?: string;
+
+  /** Main (top) navigation items. */
+  main?: SidebarItem[];
+
+  /** Footer (bottom-pinned) items. */
+  footer?: SidebarItem[];
+
+  /** Per-part style overrides (CSS custom properties / inline styles). */
+  styles?: StyleMap<SidebarParts>;
+}
+```
+
+---
+
+## `SidebarItem` union
+
+`SidebarItem` is the union of all six item types below.
+
+### `SidebarLinkConfig` — `type: 'link'`
+
+A single navigation link. Highlights automatically when the current URL matches `href` (or `pattern`).
+
+```typescript
+interface SidebarLinkConfig {
+  type: 'link';
+  label: string | DirectiveResult;
+  href: string;
+  icon?: string;
+  /** Override the URL matching pattern. Accepts a string or URLPattern. */
+  pattern?: string | URLPattern;
+  styles?: StyleMap<'host' | 'base' | 'icon' | 'label'>;
+}
+```
+
+Example:
+
+```typescript
+{ type: 'link', icon: 'dashboard', label: 'Dashboard', href: '/' }
+```
+
+---
+
+### `SidebarGroupConfig` — `type: 'group'`
+
+Collapsible group that contains links.
+
+```typescript
+interface SidebarGroupConfig {
+  type: 'group';
+  icon: string;
+  label: string | DirectiveResult;
+  items: SidebarLinkConfig[];
+  /** Start collapsed. Default: true */
+  collapsed?: boolean;
+  styles?: StyleMap<'host' | 'header' | 'icon' | 'label' | 'caret' | 'items'>;
+}
+```
+
+Example:
+
+```typescript
+{
+  type: 'group',
+  icon: 'settings',
+  label: 'Settings',
+  collapsed: false,
+  items: [
+    { type: 'link', label: 'Profile',  href: '/settings/profile' },
+    { type: 'link', label: 'Security', href: '/settings/security' },
+  ],
+}
+```
+
+---
+
+### `SidebarSectionConfig` — `type: 'section'`
+
+Labelled section that groups links and groups.
+
+```typescript
+interface SidebarSectionConfig {
+  type: 'section';
+  title: string | DirectiveResult;
+  subTitle?: string | DirectiveResult;
+  items: (SidebarGroupConfig | SidebarLinkConfig)[];
+  styles?: StyleMap<'host' | 'header' | 'title' | 'subtitle' | 'items'>;
+}
+```
+
+Example:
+
+```typescript
+{
+  type: 'section',
+  title: 'Administration',
+  items: [
+    { type: 'link', icon: 'users',    label: 'Users',    href: '/admin/users' },
+    { type: 'link', icon: 'database', label: 'Database', href: '/admin/db' },
+  ],
+}
+```
+
+---
+
+### `SidebarButtonConfig` — `type: 'button'`
+
+Action button — triggers a callback instead of navigating.
+
+```typescript
+interface SidebarButtonConfig {
+  type: 'button';
+  icon?: string;
+  label: string | DirectiveResult;
+  onClick: () => void;
+  styles?: StyleMap<string>;
+}
+```
+
+Example:
+
+```typescript
+{ type: 'button', icon: 'logout', label: 'Sign Out', onClick: () => auth.signOut() }
+```
+
+---
+
+### `SidebarHtmlConfig` — `type: 'html'`
+
+Renders a custom Lit template or raw HTML element. The `render` function
+receives the current sidebar state so you can adapt the content.
+
+```typescript
+interface SidebarHtmlConfig {
+  type: 'html';
+  render: (state: SidebarState) => TemplateResult<1> | HTMLElement | string;
+}
+```
+
+`SidebarState` values: `'default'` | `'slim'` | `'modal'` | `'mobile'` | `'mobile-open'`
+
+Example:
+
+```typescript
+{
+  type: 'html',
+  render: (state) => html`
+    <div class="user-card" ?hidden=${state === 'slim'}>
+      <img src="/avatar.png" />
+      <span>John Doe</span>
+    </div>
+  `,
+}
+```
+
+---
+
+## Sidebar parts
+
+Parts available for `styles` overrides on the root layout:
+
+| Part | Element |
+|------|---------|
+| `host` | Outer layout shell |
+| `mobile-header` | Top bar shown on mobile |
+| `sidebar` | Sidebar panel |
+| `sidebar-header` | Logo + title area |
+| `sidebar-main` | Scrollable main nav area |
+| `sidebar-footer` | Pinned footer area |
+| `main` | Main content area |
+| `progress` | Top progress bar |
+
+---
+
+## Responsive behaviour
+
+| Screen width | Sidebar state |
+|--------------|--------------|
+| < breakpoints[0] | `mobile` / `mobile-open` |
+| breakpoints[0] – breakpoints[1] | `slim` (icons only) |
+| > breakpoints[1] | `default` (full labels) |
+
+Default breakpoints: `[768, 1024]` px.
+Override per app:
+
+```typescript
+layout: {
+  type: 'sidebar',
+  breakpoints: [640, 1280],
+  // ...
+}
+```