@iyulab/router 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -0,0 +1,155 @@
+# Changelog
+
+## [0.7.6] - 2026-04-02
+
+### Fixed
+- Added `skills/` and `CHANGELOG.md` to npm `files` field — both were missing from the published package, making `npx skills add ./node_modules/@iyulab/router` non-functional
+
+## [0.7.5] - 2026-04-02
+
+### Changed
+- `@lit/react` promoted from optional peer dependency to direct dependency — React integration now works without a separate `@lit/react` install
+- Added Agent Skills definition (`skills/iyulab-router`) for AI agent tooling support
+
+## [0.7.4] - 2026-03-05
+
+### Fixed
+- `findOutlet()` now searches both shadow DOM and light DOM simultaneously
+
+## [0.7.3] - 2026-03-05
+
+### Changed
+- **Breaking:** Removed `RenderResult` and `FallbackRenderResult` types — `render` function return type is now `unknown`
+- **Breaking:** Moved React dependencies (`react`, `react-dom`, `@lit/react`) to optional peer dependencies — Lit-only projects no longer require a React install
+- Simplified `findOutlet` — removed shadow/light DOM branching and redundant `querySelector` traversal
+
+### Fixed
+- `UOutlet` now dynamically imports `react-dom/client` — prevents import failure in React-free environments
+- Corrected `UErrorPage` error code string mismatches (`OUTLET_NOT_FOUND` → `OUTLET_MISSING`, `RENDER_FAILED` → `CONTENT_RENDER_FAILED`)
+- Fixed edge case in `catchBasepath` where an empty `restPath` was treated as falsy, causing trailing slashes to be dropped
+- Changed `ULink.getBasepath()` fallback from `""` to `"/"` to prevent incorrect path generation on initial access
+- Applied optional chaining in `Router.go()` catch block to prevent property access errors when a primitive value is thrown
+
+## [0.7.2] - 2026-02-09
+
+### Changed
+- Updated dependencies to latest versions
+
+## [0.7.1] - 2026-02-09
+
+### Fixed
+- Fixed silent failure when passing `<u-outlet>` element directly as `Router` root (#1)
+- `findOutlet()` now recognizes the root element itself as a valid outlet
+- Improved `waitOutlet()` timeout error message with root element context for easier debugging
+
+## [0.7.0] - 2026-02-09
+
+### Added
+- `meta` field on `RouteConfig` — attach arbitrary key-value data to any route
+- `RouteContext.meta` — populated at navigation time with metadata merged from the full matched route chain (parent → child order, child overrides parent)
+
+## [0.6.2] - 2026-01-21
+
+### Changed
+- **Breaking:** Refactored `UOutlet` from `LitElement` to native `HTMLElement` for improved performance and reduced bundle size
+- **Breaking:** `UErrorPage` CSS custom properties renamed: `--route-icon-color` → `--error-icon-color`, `--route-code-color` → `--error-code-color`, `--route-message-color` → `--error-message-color`
+- `ULink` click event handling moved to host element level for better encapsulation
+- `@lit/react` moved from devDependency to dependency for proper React integration
+- `UErrorPage` replaced inline SVG icon imports with emoji icons; SVG asset files removed
+
+## [0.6.1] - 2026-01-20
+
+### Added
+- Added `global.d.ts` import to main entry point
+
+### Changed
+- Moved click event listener from root element to document level for more reliable event handling
+
+### Fixed
+- Fixed `UErrorPage` CSS syntax error (trailing semicolon in CSS block)
+- Fixed initial route loading to wait for outlet element readiness before navigation
+
+### Removed
+- Removed unused `computedHref` reactive state from `ULink`
+
+## [0.6.0] - 2026-01-15
+
+### Added
+- Dedicated `react.ts` export entry providing React-compatible `UOutlet` and `ULink` wrappers
+- `ULink` now supports the `target` attribute, enabling standard browser behavior (e.g. `_blank`)
+
+### Changed
+- Renamed custom elements: `ErrorPage` → `UErrorPage`, `Link` → `ULink`, `Outlet` → `UOutlet`
+- Refactored internal module organization
+
+## [0.5.3] - 2025-12-04
+
+### Changed
+- Removed restriction that prevented re-navigation to the current URL
+
+## [0.5.2] - 2025-11-17
+
+### Added
+- `initialLoad` option on `RouterConfig` — controls whether the router navigates to the current URL on initialization
+- `fallback` option on `RouterConfig` — defines a custom render function for error and not-found states
+- `RouteProgressEvent` dispatched during async route loading
+
+### Changed
+- Renamed `RouteInfo` to `RouteContext`; added `progress` callback to context for reporting load progress
+- Improved error handling and display in the built-in error page component
+
+### Removed
+- Removed `children` from `NonIndexRouteConfig` to simplify the type interface
+- Removed `route` property from the `window` object to reduce global namespace pollution
+
+## [0.5.1] - 2025-11-13
+
+### Fixed
+- Improved route error handling
+
+## [0.5.0] - 2025-11-12
+
+### Changed
+- Route `render` functions now support both synchronous and asynchronous return values
+
+### Removed
+- Dropped CommonJS build output — ESM only
+
+## [0.4.0] - 2025-11-11
+
+### Added
+- `destroy()` method on `Router` to cleanly remove event listeners
+- `useIntercept` option on `RouterConfig` — controls whether anchor tag clicks are intercepted for client-side routing
+- Global type declarations (`global.d.ts`)
+
+## [0.3.0] - 2025-10-28
+
+### Changed
+- **Breaking:** Complete router architecture overhaul
+- **Breaking:** `RouteConfig` split into `IndexRouteConfig` and `PathRouteConfig`
+- **Breaking:** `RouteError` converted to a class; added `NotFoundRouteError`
+- **Breaking:** Route event names changed: `route-start` → `route-begin`, `route-end` → `route-done`
+- Simplified `Outlet` rendering via a unified `renderContent` method
+
+### Added
+- Improved `ErrorPage` component styling and usability
+- Unified route rendering using render functions
+
+## [0.2.1] - 2025-10-27
+
+### Changed
+- Refactored routing mechanism for improved performance
+- Enhanced error handling with custom error pages
+
+### Removed
+- Removed `connect()` and `disconnect()` methods from `Router`
+- Removed `notfound` configuration option
+- Removed legacy route progress events
+- added ErrorPage component for error handling
+- added Route events: `route-start`, `route-end`, `route-error`
+- improved TypeScript types and interfaces
+
+## [0.1.0] - 2025-04-25
+
+### Added
+- Initial release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -19,8 +19,10 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "type": "module",

package/skills/iyulab-router/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: iyulab-router
+description: Client-side SPA router for Lit and React with URLPattern-based matching, nested routes, fallback handling, and route events. Use when working with @iyulab/router — setting up routing, defining routes, handling navigation, nested layouts with <u-outlet>, or listening to route lifecycle events.
+license: MIT
+compatibility: Browser environments only (requires URLPattern and History API)
+metadata:
+  author: iyulab
+  version: "0.7.4"
+---
+
+# @iyulab/router
+
+Client-side router supporting Lit and React renders, nested routes, and URLPattern-based matching.
+
+## Install
+
+```bash
+npm install @iyulab/router
+```
+
+## Core API
+
+| Export | Purpose |
+|---|---|
+| `Router` | Main router class |
+| `RouteConfig` | Route definition type |
+| `RouterConfig` | Constructor config type |
+| `RouteContext` | Passed to every `render()` call |
+| `FallbackRouteConfig` | Error/404 fallback definition |
+| `<u-outlet>` | Renders the matched route output |
+| `<u-link>` | Client-side navigation anchor |
+| `UOutlet`, `ULink` | React wrappers (from `@iyulab/router/react`) |
+
+## Router Setup
+
+```ts
+import { Router } from '@iyulab/router';
+import { html } from 'lit';
+
+const router = new Router({
+  root: document.body,       // required — mount element containing <u-outlet>
+  basepath: '/',             // optional
+  routes: [
+    { index: true, render: () => html`<home-page></home-page>` },
+    { path: '/user/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
+  ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`
+  }
+});
+```
+
+## RouteConfig Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `path` | `string \| URLPattern` | URLPattern path; omit when `index: true` |
+| `index` | `true` | Marks route as index of its parent path |
+| `render` | `(ctx) => unknown` | Returns Lit `TemplateResult`, React element, or `HTMLElement` |
+| `children` | `RouteConfig[]` | Nested routes; parent must render `<u-outlet>` |
+| `title` | `string` | Sets `document.title` on match |
+| `meta` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
+| `force` | `boolean` | Force re-render on URL change (default `true` for leaf routes) |
+
+## RouteContext Fields
+
+```ts
+ctx.params     // URLPattern captured params
+ctx.pathname   // path without query/hash
+ctx.path       // full path including query + hash
+ctx.query      // URLSearchParams
+ctx.meta       // merged meta from matched route chain
+ctx.progress   // (value: number) => void — report 0–100 loading progress
+```
+
+## Nested Routes
+
+Parent must include `<u-outlet>` in its render output:
+
+```ts
+{
+  path: '/dashboard',
+  render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
+  children: [
+    { index: true, render: () => html`<dashboard-home></dashboard-home>` },
+    { path: 'settings', render: () => html`<dashboard-settings></dashboard-settings>` }
+  ]
+}
+```
+
+## Navigation
+
+```ts
+router.go('/path');                  // programmatic navigation
+router.go('relative-path');         // relative to basepath
+router.destroy();                   // remove event listeners
+
+// From Lit template
+html`<u-link href="/about">About</u-link>`
+
+// From React
+import { ULink } from '@iyulab/router/react';
+<ULink href="/about">About</ULink>
+```
+
+## Route Events (window)
+
+| Event | Fired when |
+|---|---|
+| `route-begin` | Navigation starts |
+| `route-progress` | Async progress update (0–100) |
+| `route-done` | Navigation completes |
+| `route-error` | Routing error occurs |
+
+## Error Types (fallback ctx.error)
+
+| Code | Class |
+|---|---|
+| `NOT_FOUND` | `NotFoundError` |
+| `CONTENT_LOAD_ERROR` | `ContentLoadError` |
+| `CONTENT_RENDER_ERROR` | `ContentRenderError` |
+
+See [references/REFERENCE.md](references/REFERENCE.md) for URL parameter patterns, React usage, and advanced examples.

package/skills/iyulab-router/references/REFERENCE.md

@@ -0,0 +1,175 @@
+# @iyulab/router — Reference
+
+## URL Parameter Patterns
+
+```ts
+// Required
+{ path: '/user/:id' }
+
+// Optional
+{ path: '/posts/:category?' }
+
+// Wildcard (catch-all)
+{ path: '/docs/:path*' }
+
+// Multiple
+{ path: '/org/:orgId/repo/:repoId' }
+```
+
+Access via `ctx.params.id`, `ctx.params.category`, etc.
+
+## Query String
+
+```ts
+// URL: /search?q=hello&page=2
+ctx.query.get('q')     // 'hello'
+ctx.query.get('page')  // '2'
+```
+
+## Route Meta
+
+Meta from the full matched chain is merged (parent → child, child overrides):
+
+```ts
+{
+  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>`;
+  },
+  children: [
+    {
+      path: 'settings',
+      meta: { role: 'superadmin' },
+      render: (ctx) => {
+        // ctx.meta === { requiresAuth: true, layout: 'admin', role: 'superadmin' }
+        return html`<admin-settings></admin-settings>`;
+      }
+    }
+  ]
+}
+```
+
+## Async Render with Progress
+
+```ts
+{
+  path: '/user/:id',
+  render: async (ctx) => {
+    ctx.progress(20);
+    const user = await fetchUser(ctx.params.id);
+    ctx.progress(80);
+    return html`<user-profile .data=${user}></user-profile>`;
+  }
+}
+```
+
+## Route Events
+
+```ts
+window.addEventListener('route-begin', (e) => {
+  console.log('navigating to:', e.context.pathname);
+});
+
+window.addEventListener('route-progress', (e) => {
+  progressBar.value = e.progress; // 0–100
+});
+
+window.addEventListener('route-done', (e) => {
+  analytics.track(e.context.pathname);
+});
+
+window.addEventListener('route-error', (e) => {
+  errorTracker.report(e.error);
+});
+```
+
+## Error Fallback
+
+```ts
+fallback: {
+  render: (ctx) => {
+    const { code, message } = ctx.error;
+    if (code === 'NOT_FOUND') return html`<not-found-page></not-found-page>`;
+    return html`<error-page .message=${message}></error-page>`;
+  }
+}
+```
+
+## React Usage
+
+```tsx
+import { UOutlet, ULink } from '@iyulab/router/react';
+
+export function AppRoot() {
+  return (
+    <div>
+      <nav>
+        <ULink href="/">Home</ULink>
+        <ULink href="/about">About</ULink>
+      </nav>
+      <main>
+        <UOutlet />
+      </main>
+    </div>
+  );
+}
+```
+
+Mixed Lit + React routes:
+
+```ts
+const routes = [
+  {
+    path: '/lit-page',
+    render: () => html`<my-lit-component></my-lit-component>`
+  },
+  {
+    path: '/react-page',
+    render: () => <MyReactComponent />
+  },
+  {
+    path: '/raw-element',
+    render: (ctx) => {
+      const el = document.createElement('my-element');
+      el.data = ctx.params;
+      return el;
+    }
+  }
+];
+```
+
+## RouterConfig Options
+
+| Option | Default | Description |
+|---|---|---|
+| `root` | — | Mount element (required) |
+| `basepath` | `'/'` | URL base path |
+| `routes` | `[]` | Route definitions |
+| `fallback` | built-in error page | Error/404 handler |
+| `useIntercept` | `true` | Intercept `<a>` clicks for client routing |
+| `initialLoad` | `true` | Auto-navigate to current URL on init |
+
+## Lit Element Integration
+
+```ts
+import "@iyulab/router"; // registers <u-outlet> and <u-link>
+import { LitElement, html } from 'lit';
+import { customElement } from 'lit/decorators.js';
+
+@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>
+      </nav>
+      <main>
+        <u-outlet></u-outlet>
+      </main>
+    `;
+  }
+}
+```