@iyulab/modern-app 0.18.11 → 0.18.17

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## [0.18.17] - 2026-09-03
+
+### Fixed
+
+- **`AppConfig.auth` (the boot-time auth gate) and its `AuthGateConfig`/`AuthGateContext`
+  types were entirely undocumented in both reference docs** — the feature has a full worked
+  example in the README but no type reference anywhere a consumer would look one up. Also
+  documented `app.user` (the authenticated-user getter), and added `enter`/`initialLoad`/
+  `useIntercept` — three more real `AppConfig` fields missing specifically from
+  `skills/modern-app/references/api.md`.
+- **`FallbackRouteConfig.title` was dropped by `0.18.13`**, which only touched the `render`
+  callback's context type and didn't notice it removed the field. Restored in both docs.
+  Found by a new internal tool (`type-doc-check.js`) that diffs hand-copied TS interface doc
+  snippets against source.
+
+## [0.18.16] - 2026-09-03
+
+### Fixed
+
+- **`ThemeInitOptions.store`'s type documented a `'sessionStorage'` value that has
+  never existed.** The field's real type is re-exported unchanged from
+  `@iyulab/components`' `BrowserStorageOptions`, which only supports
+  `'localStorage' | 'cookie'` — confirmed against `BrowserStorage.ts` and its test
+  suite, which uses `'sessionStorage'` specifically as the invalid-type negative
+  case. All three docs (`docs/theme.md`, `docs/configuration.md`,
+  `skills/modern-app/references/api.md`) listed it as valid.
+
+## [0.18.15] - 2026-09-02
+
+### Fixed
+
+- **`NotificationOptions.position` documented only 4 of the 9 valid values in
+  four places** (`docs/notifications.md`, `docs/configuration.md`,
+  `skills/modern-app/references/api.md`, `skills/modern-app/SKILL.md`).
+  The field's actual type is `ToastPosition` (`@iyulab/components`, re-exported
+  unchanged) and `App.ts` passes `options` straight through to `Toast.*()` with
+  no restriction — `app.success(msg, { position: 'middle-center' })` genuinely
+  works today. Docs narrowed it to `'top-right' | 'top-left' | 'bottom-right'
+  | 'bottom-left'`, silently hiding `top-center`, `middle-left`,
+  `middle-center`, `middle-right`, and `bottom-center`.
+
+## [0.18.14] - 2026-09-02
+
+### Fixed
+
+- **`SidebarLayoutConfig`'s `mainAriaLabel` and `hasPermission` fields were
+  undocumented in all three reference docs** (`docs/layout.md`,
+  `docs/configuration.md`, `skills/modern-app/references/layout.md`). Both
+  are real, shipped features — `mainAriaLabel` sets the main nav landmark's
+  `aria-label`, `hasPermission` filters sidebar items by permission — and
+  the README already has a working usage example for `hasPermission`, but
+  a consumer reading only the type reference had no way to discover either
+  field. Added to all three snippets.
+
+## [0.18.13] - 2026-09-02
+
+### Fixed
+
+- **`RouteContext`'s documented field list had drifted independently of
+  `RouteConfig`'s.** `0.18.12` fixed `RouteConfig`'s snippet in two of three
+  docs but left `RouteContext` untouched everywhere, and `configuration.md`'s
+  `RouteConfig` snippet was missed entirely. `docs/configuration.md` and
+  `docs/routing.md` were both missing `origin`, `path`, and `hash`
+  (`routing.md` also missing `metadata`, despite `RouteConfig.metadata`'s own
+  doc comment on the line above pointing to it); `skills/modern-app/references/api.md`
+  was missing `origin`, `path`, `query`, `hash`, and `metadata` — a consumer
+  reading only that doc had no way to discover `ctx.query` exists at all.
+  `configuration.md`'s `RouteConfig` snippet gained `id`, `ignoreCase`, and
+  `children`, matching the other two docs. `FallbackRouteConfig`'s `render`
+  callback is now typed `RouteContext & { error: RouteError }` — what
+  `Router.ts` actually passes — instead of plain `RouteContext` or an
+  untyped prose note.
+
+## [0.18.12] - 2026-09-01
+
+### Fixed
+
+- **Routing docs never mentioned nested routes (`RouteConfig.children`).**
+  `@iyulab/router`'s `RouteConfig` supports it and its own README documents
+  it, but `modern-app`'s `docs/routing.md` and `skills/modern-app/references/api.md`
+  only reproduced a partial `RouteConfig` snippet that omitted `children`,
+  `id`, `ignoreCase`, and `enter`, and narrowed `path` to `string` only. A
+  consumer reading only `modern-app`'s docs had no way to discover the
+  feature and would flatten routes that share a layout into a single list.
+  Both docs now cover the full shape and link to `@iyulab/router`'s README
+  as the source of truth, and `docs/routing.md` gained a "Nested routes"
+  section with an example.
+
 ## [0.18.11] - 2026-09-01
 
 ### Changed

package/dist/_virtual/{_@oxc-project_runtime@0.147.0 → _@oxc-project_runtime@0.148.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.147.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/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.147.0 → _@oxc-project_runtime@0.148.0}/helpers/esm/decorateMetadata.js

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

package/dist/components/ActionBar.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { slotHasContent as r } from "../internals/slotted.js";
 import { styles as i } from "./ActionBar.styles.js";

package/dist/components/EmptyState.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/GroupBox.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { slotHasContent as r } from "../internals/slotted.js";
 import { styles as i } from "./GroupBox.styles.js";

package/dist/components/InfoField.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./InfoField.styles.js";
 import { html as i } from "lit";

package/dist/components/InfoSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./InfoSection.styles.js";
 import { html as i } from "lit";

package/dist/components/MasterDetailLayout.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/PageHeader.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/SidebarButton.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { styles as i } from "./SidebarButton.styles.js";

package/dist/components/SidebarGroup.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { SidebarLink as i } from "./SidebarLink.js";

package/dist/components/SidebarLink.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { styles as i } from "./SidebarLink.styles.js";

package/dist/components/SidebarSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/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/components/Wizard.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { styles as i } from "./Wizard.styles.js";

package/dist/internals/StyledElement.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/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.js

@@ -1,7 +1,7 @@
 import { app as e } from "../App.js";
 import { filterSidebarItems as t } from "./filterSidebarItems.js";
-import n from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorateMetadata.js";
-import r from "../_virtual/_@oxc-project_runtime@0.147.0/helpers/esm/decorate.js";
+import n from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import r from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
 import { StyledElement as i } from "../internals/StyledElement.js";
 import { getLocaleStrings as a } from "../internals/locale.js";
 import "../components/SidebarSection.js";

package/package.json

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

package/skills/modern-app/SKILL.md

@@ -105,7 +105,7 @@ await app.warning('Check your input');
 await app.error('Something went wrong');
 ```
 
-`position` values: `'top-right'` | `'top-left'` | `'bottom-right'` | `'bottom-left'`  
+`position` values: `'top-left'` | `'top-center'` | `'top-right'` | `'middle-left'` | `'middle-center'` | `'middle-right'` | `'bottom-left'` | `'bottom-center'` | `'bottom-right'`  
 `duration` default: `3000` ms
 
 ---

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

@@ -19,6 +19,18 @@ interface AppConfig {
   /** Fallback rendered on 404 or unhandled errors. */
   fallback?: FallbackRouteConfig;
 
+  /**
+   * Global auth/authorization guard, called before every navigation.
+   * `string` = redirect, `false` = cancel (403), `true`/undefined = proceed.
+   */
+  enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+
+  /** Auto-navigate to the current URL on load. Default: true */
+  initialLoad?: boolean;
+
+  /** Intercept `<a>` tag clicks for client-side routing. Default: true */
+  useIntercept?: boolean;
+
   /** Layout configuration. Currently only 'sidebar' is supported. */
   layout: LayoutConfig;
 
@@ -27,6 +39,12 @@ interface AppConfig {
 
   /** i18next options plus optional plugins array. Omit to skip i18n. */
   i18n?: I18nInitOptions;
+
+  /**
+   * Boot-time auth gate. When set, resolves the session via `me()` before the app shell
+   * is built. Omit for full backward compatibility (no gate). See `AuthGateConfig` below.
+   */
+  auth?: AuthGateConfig;
 }
 ```
 
@@ -57,11 +75,10 @@ interface ThemeInitOptions {
    * Persist the user's preference.
    * Set to `false` to disable persistence.
    * Default: localStorage with no prefix.
+   * `type: 'cookie'` also accepts path/domain/expires/sameSite/partitioned — see
+   * `@iyulab/components`'s `BrowserStorage` reference. No `'sessionStorage'` backend exists.
    */
-  store?: false | {
-    type: 'cookie' | 'localStorage' | 'sessionStorage';
-    prefix?: string;
-  };
+  store?: false | { type: 'localStorage'; prefix?: string } | { type: 'cookie'; prefix?: string };
 
   /** Apply built-in CSS custom properties. Default: true */
   useBuiltIn?: boolean;
@@ -72,13 +89,18 @@ interface ThemeInitOptions {
 
 ## `RouteConfig`
 
+`RouteConfig` is re-exported unchanged from `@iyulab/router` — see its README for the full
+reference. Supports `children: RouteConfig[]` for nested routes (a matched parent renders
+its own `<u-outlet>` to host the matched child) — see `docs/routing.md`'s "Nested routes"
+section for an example.
+
 ```typescript
 interface RouteConfig {
   /** Matches the root path (equivalent to `path: ''`). */
   index?: boolean;
 
-  /** Path string. Supports `:param` segments. */
-  path?: string;
+  /** Path string or `URLPattern`. Supports `:param` segments. */
+  path?: string | URLPattern;
 
   /** Sets `document.title` when the route activates. */
   title?: string;
@@ -86,6 +108,26 @@ interface RouteConfig {
   /** Force a re-render even if the path did not change. */
   force?: boolean;
 
+  /** Case-insensitive path matching. Defaults to `false`. */
+  ignoreCase?: boolean;
+
+  /** Identifier used internally by the router (auto-generated if omitted). */
+  id?: string;
+
+  /** Metadata merged parent → child, exposed on `RouteContext.metadata`. */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Guard called before this route activates.
+   * - Return a `string` to redirect.
+   * - Return `false` to cancel navigation.
+   * - Return `true` (or nothing) to proceed.
+   */
+  enter?: (context: RouteContext) => Promise<string | boolean> | string | boolean;
+
+  /** Child routes, matched relative to this route's path. */
+  children?: RouteConfig[];
+
   /** Render function. May be async. */
   render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
 }
@@ -100,14 +142,29 @@ interface RouteContext {
   /** Full URL string. */
   href: string;
 
-  /** Pathname portion of the URL. */
-  pathname: string;
+  /** Domain name portion of the URL (e.g. `https://example.com`). */
+  origin: string;
 
   /** Configured basepath. */
   basepath: string;
 
+  /** Full path including query string and hash. */
+  path: string;
+
+  /** Pathname portion of the URL. */
+  pathname: string;
+
   /** Named URL parameters extracted from the path pattern. */
-  params: Record<string, string>;
+  params: Record<string, string | undefined>;
+
+  /** Parsed query string. `query.get('key')` returns `string | null`. */
+  query: URLSearchParams;
+
+  /** Hash portion of the URL, if present. */
+  hash?: string;
+
+  /** Metadata merged parent → child from the matched route chain. */
+  metadata: Record<string, unknown>;
 
   /**
    * Report loading progress (0–100).
@@ -123,12 +180,15 @@ interface RouteContext {
 
 ```typescript
 interface FallbackRouteConfig {
-  render: (context: RouteContext) => RenderResult | Promise<RenderResult>;
+  /** Sets `document.title` when the fallback renders. */
+  title?: string;
+
+  render: (context: RouteContext & { error: RouteError }) => RenderResult | Promise<RenderResult>;
 }
 ```
 
-The fallback `RouteContext` will include an `error` property when triggered by
-a routing error.
+`RouteError` is importable from `@iyulab/router` (`code`/`original`/`timestamp` alongside the
+inherited `message`) — always populated when the fallback fires.
 
 ---
 
@@ -149,7 +209,40 @@ type I18nInitOptions = i18next.InitOptions & {
 interface NotificationOptions {
   title?: string;
   duration?: number;   // milliseconds, default 3000
-  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  position?: 'top-left' | 'top-center' | 'top-right'
+    | 'middle-left' | 'middle-center' | 'middle-right'
+    | 'bottom-left' | 'bottom-center' | 'bottom-right';
+}
+```
+
+---
+
+## `AuthGateConfig` / `AuthGateContext`
+
+The framework owns only the orchestration (check → branch → reload) — session lookup/login itself
+(HTTP), the user/permission shape, and mid-session 401 handling belong to the app (or
+`@iyulab/enterprise`'s `createAuthClient`/`createODataService`).
+
+```typescript
+interface AuthGateConfig {
+  /** Resolve the current session. Return a value for authenticated, `null`/`undefined` for not. */
+  me: () => Promise<unknown | null | undefined> | unknown | null | undefined;
+
+  /**
+   * Renders login UI into `context.root` when unauthenticated. Call `context.onSuccess()` on
+   * success. Return a cleanup function to have it called on app load/`unload`.
+   */
+  renderLogin: (context: AuthGateContext) => (() => void) | void;
+
+  /** Called once authenticated, right before the app shell is built. */
+  onAuthenticated?: (user: unknown) => void | Promise<void>;
+}
+
+interface AuthGateContext {
+  /** Root element to render the login UI into (same as `AppConfig.root`, default `document.body`). */
+  root: Element;
+  /** Call on successful login — the app (re)loads and the shell appears. */
+  onSuccess: () => void;
 }
 ```
 
@@ -175,5 +268,6 @@ interface NotificationOptions {
 | `config` | `AppConfig \| undefined` | Current config passed to `load()` |
 | `router` | `Router \| undefined` | Underlying `@iyulab/router` instance |
 | `screen` | `ScreenSize \| undefined` | Current responsive screen size |
+| `user` | `unknown` | Authenticated user when the `auth` boot gate is used; `undefined` if unauthenticated or unused |
 | `theme` | `Theme` (static) | Theme utility (`get`, `set`, `isInitialized`) |
 | `i18n` | `i18next` | Raw i18next instance |

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

@@ -18,6 +18,12 @@ interface SidebarLayoutConfig {
   /** Footer (bottom-pinned) items. */
   footer?: SidebarItem[];
 
+  /** Accessible name for the main nav landmark (`<nav class="sidebar-main">`), reflected as `aria-label`. Unset by default. */
+  mainAriaLabel?: string;
+
+  /** Permission filter — hides items (and emptied section/groups) whose requirement fails. Unset shows everything. See "권한 기반 메뉴 필터" below. */
+  hasPermission?: (code: string) => boolean;
+
   /** Per-part style overrides (CSS custom properties / inline styles). */
   styles?: StyleMap<SidebarParts>;
 }