@fukict/router 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,598 @@
+# @fukict/router
+
+SPA router for Fukict framework with nested routing, lazy loading, and navigation guards.
+
+## Features
+
+- **Nested Routes**: Multi-level route hierarchies with automatic depth management
+- **Lazy Loading**: Dynamic component loading for code splitting
+- **Navigation Guards**: `beforeEach`, `afterEach`, and route-level `beforeEnter` hooks
+- **Route Parameters**: Dynamic segments with `:param` syntax
+- **Query Parameters**: URL query string support
+- **Hash & History Mode**: Choose between hash-based or HTML5 history routing
+- **Type-Safe**: Full TypeScript support with route type inference
+- **Link Component**: Declarative navigation with automatic active states
+- **Programmatic Navigation**: `push()`, `replace()`, `back()`, `forward()` methods
+- **Route Meta**: Attach custom metadata to routes
+
+## Installation
+
+```bash
+pnpm add @fukict/router @fukict/basic
+```
+
+## Quick Start
+
+### Basic Setup
+
+```tsx
+import { Fukict, attach } from '@fukict/basic';
+import { Link, RouteComponent, RouterProvider } from '@fukict/router';
+
+// Define page components
+class HomePage extends RouteComponent {
+  render() {
+    return (
+      <div>
+        <h1>Home Page</h1>
+        <Link to="/about">Go to About</Link>
+      </div>
+    );
+  }
+}
+
+class AboutPage extends RouteComponent {
+  render() {
+    return <h1>About Page</h1>;
+  }
+}
+
+// Configure routes
+const routes = [
+  { path: '/', component: HomePage },
+  { path: '/about', component: AboutPage },
+];
+
+// Create app with RouterProvider
+class App extends Fukict {
+  render() {
+    return (
+      <div>
+        <nav>
+          <Link to="/">Home</Link>
+          <Link to="/about">About</Link>
+        </nav>
+        <RouterProvider routes={routes} />
+      </div>
+    );
+  }
+}
+
+attach(<App />, document.getElementById('app')!);
+```
+
+## Core Concepts
+
+### Route Configuration
+
+```typescript
+import type { RouteConfig } from '@fukict/router';
+
+const routes: RouteConfig[] = [
+  {
+    path: '/',
+    component: HomePage,
+    meta: { title: 'Home' },
+  },
+  {
+    path: '/users/:id',
+    component: UserPage,
+    meta: { title: 'User Profile', requiresAuth: true },
+    beforeEnter: (to, from, next) => {
+      // Route-level guard
+      if (isAuthenticated()) {
+        next();
+      } else {
+        next('/login');
+      }
+    },
+  },
+  {
+    path: '/dashboard',
+    component: DashboardLayout,
+    children: [
+      {
+        path: '/dashboard/overview',
+        component: OverviewPage,
+      },
+      {
+        path: '/dashboard/settings',
+        component: SettingsPage,
+      },
+    ],
+  },
+  {
+    path: '*',
+    component: NotFoundPage,
+  },
+];
+```
+
+### RouterProvider Options
+
+```tsx
+import { RouterProvider } from '@fukict/router';
+
+<RouterProvider
+  routes={routes}
+  mode="hash" // or "history"
+  beforeEach={(to, from, next) => {
+    // Global before guard
+    console.log('Navigating:', from.path, '->', to.path);
+    document.title = to.meta?.title || 'App';
+    next();
+  }}
+  afterEach={(to, from) => {
+    // Global after hook
+    console.log('Navigation complete');
+  }}
+/>;
+```
+
+### RouteComponent Base Class
+
+Extend `RouteComponent` for convenient access to routing APIs:
+
+```tsx
+import { RouteComponent } from '@fukict/router';
+
+class UserPage extends RouteComponent {
+  mounted() {
+    // Access route information
+    console.log('Route path:', this.route.path);
+    console.log('Params:', this.params);
+    console.log('Query:', this.query);
+  }
+
+  // Listen to parameter changes
+  routeParamsChanged(newParams: any, oldParams: any) {
+    console.log('Params changed:', oldParams, '->', newParams);
+    // Re-fetch data based on new params
+    this.loadUser(newParams.id);
+  }
+
+  // Listen to query changes
+  routeQueryChanged(newQuery: any, oldQuery: any) {
+    console.log('Query changed:', oldQuery, '->', newQuery);
+  }
+
+  loadUser(id: string) {
+    // Load user data
+  }
+
+  goHome = () => {
+    this.push('/');
+  };
+
+  render() {
+    const { id } = this.params;
+    const { page = '1' } = this.query;
+
+    return (
+      <div>
+        <h1>User {id}</h1>
+        <p>Page: {page}</p>
+        <button on:click={this.goHome}>Go Home</button>
+      </div>
+    );
+  }
+}
+```
+
+### Link Component
+
+```tsx
+import { Link } from '@fukict/router';
+
+// Basic link
+<Link to="/about">About</Link>
+
+// With query parameters
+<Link to={{ path: '/search', query: { q: 'fukict', page: '1' } }}>
+  Search
+</Link>
+
+// Replace mode (doesn't add history entry)
+<Link to="/login" replace>Login</Link>
+
+// Custom active class
+<Link to="/" activeClass="nav-active" exactActiveClass="nav-exact">
+  Home
+</Link>
+
+// Styled link
+<Link to="/profile" className="nav-link">
+  <span>Profile</span>
+</Link>
+```
+
+### Programmatic Navigation
+
+```tsx
+class MyComponent extends RouteComponent {
+  handleSubmit = () => {
+    // Push new route
+    this.push('/success');
+
+    // Push with query
+    this.push({ path: '/search', query: { q: 'test' } });
+
+    // Replace current route
+    this.replace('/login');
+
+    // Update query only
+    this.updateQuery({ page: '2', sort: 'date' });
+
+    // Go back
+    this.back();
+
+    // Go forward
+    this.forward();
+
+    // Access router directly
+    this.router.push('/custom');
+  };
+
+  render() {
+    return <button on:click={this.handleSubmit}>Submit</button>;
+  }
+}
+```
+
+## Nested Routes
+
+### Parent-Child Structure
+
+```tsx
+// Parent layout component
+class DashboardLayout extends RouteComponent {
+  render() {
+    return (
+      <div class="dashboard">
+        <aside>
+          <Link to="/dashboard/overview">Overview</Link>
+          <Link to="/dashboard/analytics">Analytics</Link>
+          <Link to="/dashboard/settings">Settings</Link>
+        </aside>
+        <main>
+          {/* Render child routes here */}
+          <RouterView router={this.router} />
+        </main>
+      </div>
+    );
+  }
+}
+
+// Child components
+class OverviewPage extends RouteComponent {
+  render() {
+    return <h2>Dashboard Overview</h2>;
+  }
+}
+
+class AnalyticsPage extends RouteComponent {
+  render() {
+    return <h2>Analytics</h2>;
+  }
+}
+
+// Route configuration
+const routes = [
+  {
+    path: '/dashboard',
+    component: DashboardLayout,
+    children: [
+      { path: '/dashboard/overview', component: OverviewPage },
+      { path: '/dashboard/analytics', component: AnalyticsPage },
+      { path: '/dashboard/settings', component: SettingsPage },
+    ],
+  },
+];
+```
+
+## Navigation Guards
+
+### Global Guards
+
+```tsx
+<RouterProvider
+  routes={routes}
+  beforeEach={(to, from, next) => {
+    // Authentication check
+    if (to.meta?.requiresAuth && !isLoggedIn()) {
+      next('/login');
+      return;
+    }
+
+    // Update page title
+    document.title = to.meta?.title || 'App';
+
+    // Proceed
+    next();
+  }}
+  afterEach={(to, from) => {
+    // Analytics tracking
+    trackPageView(to.path);
+
+    // Scroll to top
+    window.scrollTo(0, 0);
+  }}
+/>
+```
+
+### Route-Level Guards
+
+```typescript
+const routes = [
+  {
+    path: '/admin',
+    component: AdminPage,
+    beforeEnter: (to, from, next) => {
+      if (isAdmin()) {
+        next();
+      } else {
+        next('/forbidden');
+      }
+    },
+  },
+];
+```
+
+### Guard Execution Order
+
+```
+Global beforeEach
+    ↓
+Route beforeEnter
+    ↓
+Component mount/update
+    ↓
+Global afterEach
+```
+
+## Route Parameters
+
+### Dynamic Segments
+
+```typescript
+// Route config
+{ path: '/users/:id', component: UserPage }
+{ path: '/posts/:category/:id', component: PostPage }
+
+// Access in component
+class UserPage extends RouteComponent {
+  render() {
+    const { id } = this.params;
+    return <h1>User {id}</h1>;
+  }
+
+  // React to param changes
+  routeParamsChanged(newParams: any, oldParams: any) {
+    console.log('User changed from', oldParams.id, 'to', newParams.id);
+  }
+}
+```
+
+### Query Parameters
+
+```typescript
+// Navigate with query
+this.push({ path: '/search', query: { q: 'fukict', page: '1' } });
+
+// Access in component
+class SearchPage extends RouteComponent {
+  render() {
+    const { q, page = '1' } = this.query;
+    return (
+      <div>
+        <h1>Search: {q}</h1>
+        <p>Page: {page}</p>
+      </div>
+    );
+  }
+
+  // Update query
+  nextPage = () => {
+    const currentPage = parseInt(this.query.page || '1');
+    this.updateQuery({ page: String(currentPage + 1) });
+  };
+
+  // React to query changes
+  routeQueryChanged(newQuery: any, oldQuery: any) {
+    this.performSearch(newQuery.q, newQuery.page);
+  }
+}
+```
+
+## Lazy Loading
+
+```typescript
+// Define lazy component loader
+const LazyPage = () => import('./pages/LazyPage');
+
+// Route configuration
+const routes = [
+  {
+    path: '/lazy',
+    component: LazyPage, // Will be loaded on demand
+  },
+];
+```
+
+## Route Metadata
+
+```typescript
+// Define custom route meta
+interface RouteMeta {
+  title?: string;
+  requiresAuth?: boolean;
+  roles?: string[];
+}
+
+// Use in routes
+const routes: RouteConfig[] = [
+  {
+    path: '/admin',
+    component: AdminPage,
+    meta: {
+      title: 'Admin Panel',
+      requiresAuth: true,
+      roles: ['admin'],
+    } as RouteMeta,
+  },
+];
+
+// Access in guards
+beforeEach: (to, from, next) => {
+  const meta = to.meta as RouteMeta;
+  if (meta?.requiresAuth && !isAuthenticated()) {
+    next('/login');
+  } else {
+    next();
+  }
+};
+```
+
+## Advanced Usage
+
+### Router Instance
+
+```tsx
+import { Router } from '@fukict/router';
+
+// Create router manually
+const router = new Router({
+  mode: 'history',
+  routes,
+  beforeEach: (to, from, next) => {
+    // Guard logic
+    next();
+  },
+});
+
+// Use in app
+class App extends Fukict {
+  render() {
+    return <RouterView router={router} />;
+  }
+}
+```
+
+### Custom Link Styling
+
+```tsx
+<Link
+  to="/profile"
+  activeClass="text-blue-500"
+  exactActiveClass="font-bold text-blue-700"
+>
+  <span>Profile</span>
+</Link>
+```
+
+### Redirect Routes
+
+```typescript
+const routes = [
+  { path: '/', component: HomePage },
+  {
+    path: '/old-path',
+    beforeEnter: (to, from, next) => {
+      next('/new-path');
+    },
+  },
+  { path: '/new-path', component: NewPage },
+];
+```
+
+## Best Practices
+
+### 1. Use RouteComponent Base Class
+
+```tsx
+// ✅ Good: Extend RouteComponent
+class UserPage extends RouteComponent {
+  render() {
+    return <div>User {this.params.id}</div>;
+  }
+}
+
+// ❌ Bad: Manual router access
+class UserPage extends Fukict<{ router: Router }> {
+  render() {
+    const params = this.props.router.currentRoute.params;
+    return <div>User {params.id}</div>;
+  }
+}
+```
+
+### 2. Handle Parameter Changes
+
+```tsx
+// ✅ Good: Implement routeParamsChanged
+class ProductPage extends RouteComponent {
+  routeParamsChanged(newParams: any, oldParams: any) {
+    this.loadProduct(newParams.id);
+  }
+}
+
+// ❌ Bad: No reaction to param changes
+class ProductPage extends RouteComponent {
+  mounted() {
+    this.loadProduct(this.params.id);
+    // Won't reload when navigating to different product
+  }
+}
+```
+
+### 3. Organize Routes
+
+```typescript
+// ✅ Good: Modular route structure
+const userRoutes = [
+  { path: '/users', component: UserList },
+  { path: '/users/:id', component: UserDetail },
+];
+
+const adminRoutes = [
+  { path: '/admin', component: AdminDashboard },
+  { path: '/admin/users', component: AdminUsers },
+];
+
+const routes = [...userRoutes, ...adminRoutes, notFoundRoute];
+```
+
+## Examples
+
+See the [examples/infra-router](../../examples/infra-router) for complete examples:
+
+- Basic routing
+- Nested routes
+- Route parameters and query strings
+- Navigation guards
+- Lazy loading
+- 404 handling
+
+## API Reference
+
+See [docs/README.md](./docs/README.md) for detailed API documentation.
+
+## Related Packages
+
+- [@fukict/basic](../basic) - Core rendering engine (required)
+- [@fukict/babel-preset](../babel-preset) - JSX transformation
+- [@fukict/vite-plugin](../vite-plugin) - Vite integration
+
+## License
+
+MIT

package/dist/RouterView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterView.d.ts","sourceRoot":"","sources":["../src/RouterView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAgB,MAAM,eAAe,CAAC;AAGjE,OAAO,KAAK,EAAe,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,MAAM,CAAC,eAAe,CAAC;IACrD;;OAEG;IACH,OAAO,CAAC,WAAW,CAAuB;IAE1C;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,MAAM,IAAI,KAAK;CA6BhB"}
+{"version":3,"file":"RouterView.d.ts","sourceRoot":"","sources":["../src/RouterView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAa,MAAM,eAAe,CAAC;AAG9D,OAAO,KAAK,EAAe,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,MAAM,CAAC,eAAe,CAAC;IACrD;;OAEG;IACH,OAAO,CAAC,WAAW,CAAuB;IAE1C;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAezB;;OAEG;IACH,MAAM,IAAI,KAAK;CA6BhB"}

package/dist/RouterView.js

@@ -1,4 +1,4 @@
-import { Fukict, VNodeType, h } from '@fukict/basic';
+import { Fukict, VNodeType } from '@fukict/basic';
 /**
  * RouterView 组件
  *
@@ -40,26 +40,24 @@ export class RouterView extends Fukict {
         const matched = this.props.router.matched;
         // 没有匹配的路由，渲染 fallback
         if (!matched || !matched.component) {
-            return this.props.fallback || h('div', { class: 'router-view' }, []);
+            return (this.props.fallback || {
+                type: 'div',
+                __type__: VNodeType.Element,
+                props: {
+                    class: 'router-view',
+                },
+                children: [],
+            });
         }
         const RouteComp = matched.component;
         const childRouter = this.getRouterForChild(matched);
         return {
-            type: 'div',
-            __type__: VNodeType.Element,
+            type: RouteComp,
+            __type__: VNodeType.ClassComponent,
             props: {
-                class: 'router-view',
+                router: childRouter,
             },
-            children: [
-                {
-                    type: RouteComp,
-                    __type__: VNodeType.ClassComponent,
-                    props: {
-                        router: childRouter,
-                    },
-                    children: [],
-                },
-            ],
+            children: [],
         };
     }
 }

package/dist/RouterView.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouterView.js","sourceRoot":"","sources":["../src/RouterView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,SAAS,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAKjE;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,MAAuB;IACrD;;OAEG;IACK,WAAW,GAAkB,IAAI,CAAC;IAE1C;;OAEG;IACH,aAAa;QACX,QAAQ;QACR,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,OAAoB;QAC5C,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,cAAc;YACd,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACrD,CAAC;YACD,kDAAkD;YAClD,IAAI,CAAC,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC;YAC/D,OAAO,IAAI,CAAC,WAAW,CAAC;QAC1B,CAAC;QAED,oBAAoB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;QAE1C,sBAAsB;QACtB,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEpD,OAAO;YACL,IAAI,EAAE,KAAK;YACX,QAAQ,EAAE,SAAS,CAAC,OAAO;YAC3B,KAAK,EAAE;gBACL,KAAK,EAAE,aAAa;aACrB;YACD,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,SAAS;oBACf,QAAQ,EAAE,SAAS,CAAC,cAAc;oBAClC,KAAK,EAAE;wBACL,MAAM,EAAE,WAAW;qBACpB;oBACD,QAAQ,EAAE,EAAE;iBACb;aACF;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"RouterView.js","sourceRoot":"","sources":["../src/RouterView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAc,SAAS,EAAE,MAAM,eAAe,CAAC;AAK9D;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,MAAuB;IACrD;;OAEG;IACK,WAAW,GAAkB,IAAI,CAAC;IAE1C;;OAEG;IACH,aAAa;QACX,QAAQ;QACR,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,OAAoB;QAC5C,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,cAAc;YACd,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACrD,CAAC;YACD,kDAAkD;YAClD,IAAI,CAAC,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC;YAC/D,OAAO,IAAI,CAAC,WAAW,CAAC;QAC1B,CAAC;QAED,oBAAoB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;QAE1C,sBAAsB;QACtB,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YACnC,OAAO,CACL,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI;gBACrB,IAAI,EAAE,KAAK;gBACX,QAAQ,EAAE,SAAS,CAAC,OAAO;gBAC3B,KAAK,EAAE;oBACL,KAAK,EAAE,aAAa;iBACrB;gBACD,QAAQ,EAAE,EAAE;aACb,CACF,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEpD,OAAO;YACL,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,SAAS,CAAC,cAAc;YAClC,KAAK,EAAE;gBACL,MAAM,EAAE,WAAW;aACpB;YACD,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;CACF"}

package/dist/metadata.d.ts

@@ -4,7 +4,7 @@
  */
 export declare const METADATA: {
     readonly name: "@fukict/router";
-    readonly version: "0.1.0";
+    readonly version: "0.1.2";
     readonly description: "Router for Fukict framework with nested routing and lazy loading";
     readonly author: "Fukict Team";
     readonly license: "MIT";

package/dist/metadata.js

@@ -4,7 +4,7 @@
  */
 export const METADATA = {
     name: '@fukict/router',
-    version: '0.1.0',
+    version: '0.1.2',
     description: 'Router for Fukict framework with nested routing and lazy loading',
     author: 'Fukict Team',
     license: 'MIT',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fukict/router",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Router for Fukict framework with nested routing and lazy loading",
   "keywords": [
     "fukict",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@fukict/basic": "0.1.0"
+    "@fukict/basic": "0.1.2"
   },
   "devDependencies": {
     "typescript": "^5.6.3"
@@ -45,6 +45,9 @@
   "engines": {
     "node": ">=16.0.0"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "build": "tsx ../../scripts/build-package.ts --pkg-name router --no-watch",
     "dev": "tsx ../../scripts/build-package.ts --pkg-name router --watch",