@iyulab/router 0.7.6 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.9.0] - 2026-04-08
+
+### Added
+- `NavigateOptions` — new optional second parameter for `go()` with `isRedirect`, `replace`, and `state` fields
+- `replace` option — navigate without pushing a new browser history entry (`replaceState`)
+- `state` option — attach custom state object to `history.pushState` / `replaceState`
+- `AccessDeniedError` — new error class (HTTP 403) thrown when an `enter` guard returns `false`; renders an error page with `ACCESS_DENIED` code
+- Redirect cycle detection — logs an error and halts routing if the same URL is visited more than once within a single navigation chain
+- `UErrorPage` now accepts an optional `RouteError` in its constructor for direct instantiation
+
+### Changed
+- **Breaking:** `enter` returning `false` now throws `AccessDeniedError` and renders a 403 error page instead of silently aborting navigation
+- Redirect navigations (`isRedirect: true`) use `replaceState` — intermediate redirect URLs are no longer pushed onto the browser history stack
+- Global `enter` guard is skipped on redirect hops — runs only once per user-initiated navigation
+- Route-level `enter` hooks are deduplicated within a redirect chain — each route's `enter` executes at most once per navigation cycle
+- `document.title` is now updated in a `finally` block — title is set regardless of whether routing succeeds or fails
+
+## [0.8.0] - 2026-04-08
+
+### Added
+- Added navigation guards via `enter` hooks at both router level (`RouterConfig.enter`) and route level (`RouteConfig.enter`) with redirect/cancel flow support
+- Added `rel` attribute support to `<u-link>` for secure external navigation patterns (for example `noopener noreferrer`)
+
+### Changed
+- **Breaking:** Renamed route metadata fields from `meta` to `metadata` (`RouteConfig.metadata`, `RouteContext.metadata`)
+- Updated nested outlet resolution to prefer child outlet discovery inside the current outlet, improving deep nested route rendering behavior
+
 ## [0.7.6] - 2026-04-02
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @iyulab/router
 
-A modern, lightweight client-side router for web applications with support for both Lit and React components.
+Client-side SPA router for Lit and React with URLPattern matching, nested routes, and route lifecycle events.
 
 ## Installation
 
@@ -10,270 +10,136 @@ npm install @iyulab/router
 
 ## Quick Start
 
-### Basic Setup
-
 ```typescript
 import { Router } from '@iyulab/router';
 import { html } from 'lit';
 
 const router = new Router({
+  root: document.body,
   basepath: '/',
   routes: [
-    {
-      index: true,
-      render: () => html`<home-page></home-page>`
-    },
-    {
-      path: '/user/:id', // URLPattern route
-      render: (routeInfo) => html`<user-page .userId=${routeInfo.params.id}></user-page>`
-    }
+    { index: true, render: () => html`<home-page></home-page>` },
+    { path: '/users/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
   ],
-});
-```
-
-### Mixed Framework Support
-
-```typescript
-import React from 'react';
-
-const routes = [
-  // Lit component
-  {
-    path: '/lit-page',
-    render: (routeInfo) => {
-      return html`<my-lit-component .routeInfo=${routeInfo}></my-lit-component>`
-    }
-  },
-  // React component
-  {
-    path: '/react-page',
-    render: (routeInfo) => {
-      return ( <MyComponent></MyComponent> )
-    }
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`,
   },
-  // HTML element
-  {
-    path: '/element-page',
-    render: (routeInfo) => {
-      const element = document.createElement('my-element');
-      element.data = routeInfo.params;
-      return element;
-    }
-  }
-];
-```
-
-### Nested Routes
-
-```typescript
-import { RouteConfig } from '@iyulab/router';
+});
 
-const routes: RouteConfig[] = [
-  {
-    path: '/dashboard',
-    render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
-    children: [
-      {
-        index: true, // Matches '/dashboard'
-        render: () => html`<dashboard-home></dashboard-home>`
-      },
-      {
-        path: 'settings', // Matches '/dashboard/settings'
-        render: () => html`<dashboard-settings></dashboard-settings>`
-      }
-    ]
-  }
-];
+router.go('/users/1');
 ```
 
 ## Skills Usage
 
-Install the `iyulab-router` skill to give your AI agent knowledge of this package's API and patterns.
-
-**Using GitHub shorthand:**
+Install the `iyulab-router` skill for agent-friendly package guidance.
 
 ```bash
 npx skills add iyulab/node-router
 ```
 
-**Using local path (after `npm install`):**
-
 ```bash
 npx skills add ./node_modules/@iyulab/router
 ```
 
-## Usage Examples
+## Route Guards
 
-### Using with Lit Elements
-
-```typescript
-import { LitElement, html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-
-import "@iyulab/router";
-
-@customElement('app-root')
-export class AppRoot extends LitElement {
-  render() {
-    return html`
-      <nav>
-        <u-link href="/">Home</u-link>
-        <u-link href="/about">About</u-link>
-        <u-link href="/user/123">User Profile</u-link>
-      </nav>
-      <main>
-        <u-outlet></u-outlet>
-      </main>
-    `;
-  }
-}
-```
-
-### Using with React Components
-
-```tsx
-import React from 'react';
-import { UOutlet, ULink } from '@iyulab/router/react';
-
-export function AppRoot() {
-  return (
-    <div>
-      <nav>
-        <ULink href="/">Home</ULink>
-        <ULink href="/about">About</ULink>
-        <ULink href="/user/123">User Profile</ULink>
-      </nav>
-      <main>
-        <UOutlet />
-      </main>
-    </div>
-  );
-}
-```
-
-## Error Handling
-
-The router provides comprehensive error handling through `FallbackRouteContext`. When a routing error occurs, the fallback render function receives a context with full error information:
+Use `enter` to run guard logic before rendering.
 
 ```typescript
 const router = new Router({
   root: document.body,
-  basepath: '/',
-  routes: [...],
-  fallback: {
-    title: 'Error',
-    render: (ctx) => {
-      // ctx.error contains RouteError with code, message, and original error
-      const { code, message, original } = ctx.error;
-
-      if (code === 'NOT_FOUND') {
-        return html`<not-found-page .path=${ctx.pathname}></not-found-page>`;
-      }
-      if (code === 'CONTENT_LOAD_ERROR') {
-        return html`<error-page .message=${message}></error-page>`;
-      }
-      return html`<error-page .error=${ctx.error}></error-page>`;
-    }
-  }
+  enter: (ctx) => {
+    if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+    return true;
+  },
+  routes: [
+    { path: '/login', render: () => html`<login-page></login-page>` },
+    {
+      path: '/admin',
+      enter: () => hasRole('admin') || '/forbidden',
+      render: () => html`<admin-page></admin-page>`,
+    },
+  ],
 });
 ```
 
-Error types:
-- `NotFoundError` — No matching route found (code: `NOT_FOUND`)
-- `ContentLoadError` — Route render function threw an error (code: `CONTENT_LOAD_ERROR`)
-- `ContentRenderError` — Outlet rendering failed (code: `CONTENT_RENDER_ERROR`)
+`enter` return values:
+- `true` (or `undefined`): continue
+- `false`: cancel navigation
+- `string`: redirect to that path
 
 ## Route Metadata
 
-Routes can carry arbitrary metadata via the `meta` field. When a route matches, metadata from the entire matched route chain is merged (parent → child order, child overrides parent):
+Attach metadata to routes using `metadata`. The router merges metadata from parent to child and exposes it on `ctx.metadata`.
 
 ```typescript
-const router = new Router({
-  root: document.body,
-  basepath: '/',
-  routes: [
-    {
-      path: '/admin',
-      meta: { requiresAuth: true, layout: 'admin' },
-      render: (ctx) => {
-        // ctx.meta === { requiresAuth: true, layout: 'admin' }
-        return html`<admin-layout><u-outlet></u-outlet></admin-layout>`;
+const routes = [
+  {
+    path: '/dashboard',
+    metadata: { requiresAuth: true, section: 'dashboard' },
+    render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
+    children: [
+      {
+        path: 'settings',
+        metadata: { tab: 'settings' },
+        render: (ctx) => html`<settings-page .metadata=${ctx.metadata}></settings-page>`,
       },
-      children: [
-        {
-          path: 'settings',
-          meta: { requiresAuth: true, role: 'superadmin' },
-          render: (ctx) => {
-            // ctx.meta === { requiresAuth: true, layout: 'admin', role: 'superadmin' }
-            return html`<admin-settings></admin-settings>`;
-          }
-        }
-      ]
-    }
-  ]
-});
+    ],
+  },
+];
 ```
 
-Use cases: authentication guards, SEO tags, analytics tracking, layout selection, and more.
+## Nested Routes
 
-## Route Events
+Parent routes must render `<u-outlet>` to host child route content.
 
-The router dispatches events on the `window` object during navigation:
+```typescript
+const routes = [
+  {
+    path: '/nested',
+    render: () => html`<nested-layout><u-outlet></u-outlet></nested-layout>`,
+    children: [
+      { index: true, render: () => html`<nested-home></nested-home>` },
+      { path: 'lit', render: () => html`<nested-lit></nested-lit>` },
+      { path: 'react', render: () => <NestedReact /> },
+    ],
+  },
+];
+```
 
-| Event | Type | Description |
-|-------|------|-------------|
-| `route-begin` | `RouteBeginEvent` | Fired when navigation starts |
-| `route-progress` | `RouteProgressEvent` | Fired during async loading (0–100) |
-| `route-done` | `RouteDoneEvent` | Fired when navigation completes successfully |
-| `route-error` | `RouteErrorEvent` | Fired when a routing error occurs |
+## Link and Outlet Components
 
-```typescript
-// Track navigation progress
-window.addEventListener('route-progress', (e: RouteProgressEvent) => {
-  progressBar.value = e.progress;
-});
+- `<u-link>`: SPA-aware anchor element
+- `<u-outlet>`: render target for matched route output
 
-// Log navigation events
-window.addEventListener('route-begin', (e: RouteBeginEvent) => {
-  console.log('Navigating to:', e.context.pathname);
-});
+`<u-link>` supports `href`, `target`, and `rel`.
 
-window.addEventListener('route-done', (e: RouteDoneEvent) => {
-  analytics.trackPageView(e.context.pathname);
-});
+```html
+<u-link href="/docs">Docs</u-link>
+<u-link href="https://example.com" target="_blank" rel="noopener noreferrer">External</u-link>
+```
 
-window.addEventListener('route-error', (e: RouteErrorEvent) => {
-  errorTracker.report(e.error);
-});
+React wrappers:
+
+```tsx
+import { ULink, UOutlet } from '@iyulab/router/react';
 ```
 
-## URL Parameters
+## Route Events
+
+The router dispatches events on `window`:
 
-The router supports URLPattern-based parameter matching:
+- `route-begin`
+- `route-progress`
+- `route-done`
+- `route-error`
 
 ```typescript
-const routes: RouteConfig[] = [
-  // Required parameter
-  { path: '/user/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
-
-  // Optional parameter
-  { path: '/posts/:category?', render: (ctx) => {
-    const category = ctx.params.category || 'all';
-    return html`<posts-page .category=${category}></posts-page>`;
-  }},
-
-  // Wildcard (catch-all)
-  { path: '/docs/:path*', render: (ctx) => html`<docs-page .path=${ctx.params.path}></docs-page>` },
-
-  // Multiple parameters
-  { path: '/org/:orgId/repo/:repoId', render: (ctx) => {
-    return html`<repo-page .orgId=${ctx.params.orgId} .repoId=${ctx.params.repoId}></repo-page>`;
-  }}
-];
+window.addEventListener('route-progress', (e) => {
+  console.log(e.progress);
+});
 ```
 
-When URL parameters change (e.g., navigating from `/user/1` to `/user/2`), leaf routes (without children) automatically re-render since `force` defaults to `true`. For parent routes with children, set `force: true` explicitly if re-rendering is needed on parameter changes.
-
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License. See [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -3,6 +3,13 @@ import { LitElement } from 'lit';
 import { PropertyValues } from 'lit';
 import { TemplateResult } from 'lit-html';
 
+/**
+ * enter 가드가 false를 반환하여 접근이 거부되었을 때 발생하는 에러
+ */
+export declare class AccessDeniedError extends RouteError {
+    constructor(path: string);
+}
+
 /**
  * 공통 라우트 속성
  */
@@ -47,6 +54,17 @@ declare interface BaseRouteConfig {
      * ```
      */
     render?: (ctx: RouteContext) => Promise<unknown> | unknown;
+    /**
+     * 이 라우트 진입 전에 호출되는 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * { path: '/admin', enter: (ctx) => ctx.metadata.role === 'admin' || '/forbidden' }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
     /**
      * 라우터 URL 변경시 렌더링을 강제할지 여부
      * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
@@ -63,10 +81,10 @@ declare interface BaseRouteConfig {
      * - 인증, SEO, 분석 등의 용도로 사용할 수 있습니다.
      * @example
      * ```typescript
-     * { path: '/admin', meta: { requiresAuth: true, role: 'admin' } }
+     * { path: '/admin', metadata: { requiresAuth: true, role: 'admin' } }
      * ```
      */
-    meta?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
 }
 
 /**
@@ -124,6 +142,32 @@ declare interface IndexRouteConfig extends BaseRouteConfig {
     index: true;
 }
 
+/**
+ * go() 메서드에 전달할 네비게이션 옵션
+ */
+export declare interface NavigateOptions {
+    /**
+     * 리다이렉트로 인한 네비게이션 여부.
+     * - `true`이면 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - 뒤로가기 버튼이 리다이렉트 경유지를 건너뛰게 됩니다.
+     * - 리다이렉트 사이클 감지에 사용됩니다.
+     * @default false
+     */
+    isRedirect?: boolean;
+    /**
+     * 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - `isRedirect`와 달리 리다이렉트 체인 추적에는 영향을 주지 않습니다.
+     * @default false
+     */
+    replace?: boolean;
+    /**
+     * pushState / replaceState 호출 시 함께 저장할 커스텀 상태 객체.
+     * - `history.state`로 다시 읽을 수 있습니다.
+     * @example { from: '/login', referrer: 'email-link' }
+     */
+    state?: Record<string, unknown>;
+}
+
 declare interface NonIndexRouteConfig extends BaseRouteConfig {
     /**
      * 인덱스 라우트가 아님을 나타냅니다.
@@ -156,8 +200,6 @@ declare interface RenderOption {
     id?: string;
     /** 강제 렌더링 여부 */
     force?: boolean;
-    /** 렌더링할 값 */
-    value: unknown;
 }
 
 /**
@@ -244,7 +286,7 @@ export declare interface RouteContext {
      * 매칭된 라우트 체인의 병합된 메타데이터
      * - 부모 라우트에서 자식 라우트 순서로 병합됩니다.
      */
-    meta: Record<string, unknown>;
+    metadata: Record<string, unknown>;
 }
 
 /**
@@ -316,6 +358,8 @@ export declare class Router {
     private readonly _basepath;
     private readonly _routes;
     private readonly _fallback?;
+    private readonly _enter?;
+    private readonly _tracker;
     /** 현재 라우팅 요청 ID */
     private _requestID?;
     /** 현재 라우팅 정보 */
@@ -332,8 +376,9 @@ export declare class Router {
     /**
      * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
      * @param href 이동할 경로
+     * @param options 네비게이션 옵션
      */
-    go(href: string): Promise<void>;
+    go(href: string, options?: NavigateOptions): Promise<undefined>;
     /** 브라우저 히스토리 이벤트가 발생시 라우팅 처리 */
     private handleWindowPopstate;
     /** 클릭 이벤트에서 라우터로 처리할 앵커를 찾아 클라이언트 라우팅 수행 */
@@ -361,6 +406,19 @@ export declare interface RouterConfig {
      * - 라우트는 렌더링할 엘리먼트 또는 컴포넌트를 지정합니다.
      */
     routes?: RouteConfig[];
+    /**
+     * 모든 라우트 전환 전에 호출되는 글로벌 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * enter: async (ctx) => {
+     *   if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+     * }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
     /**
      * 라우트 매칭 실패 또는 오류 발생 시 대체 라우트 설정
      * - 지정된 설정이 없을 경우, 기본 오류 페이지가 렌더링됩니다.
@@ -395,6 +453,16 @@ export declare class ULink extends LitElement {
      * - `_top`: 최상위 프레임에서 링크 열기
      */
     target?: string;
+    /**
+     * 링크 관계 rel 속성
+     *
+     * - `noopener`: target이 _blank인 경우 보안 강화 (window.opener 차단)
+     * - `noreferrer`: target이 _blank인 경우 보안 강화 + Referer 헤더 제거
+     * - `external`: 외부 링크임을 명시 (SEO/접근성에 도움)
+     * - `nofollow`: 검색 엔진이 링크를 따라가지 않도록 지시 (SEO에 영향)
+     * - 그 외 rel 값도 그대로 전달됩니다.
+     */
+    rel?: string;
     /**
      * 링크 대상 URL, 다음 사항에 따라 SPA 라우팅 또는 브라우저 네비게이션이 결정됩니다.
      *
@@ -436,7 +504,7 @@ export declare class UOutlet extends HTMLElement {
     /**
      * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
      */
-    render({ id, value, force }: RenderOption): Promise<void>;
+    render(value: unknown, options?: RenderOption): Promise<void>;
     /**
      * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
      */