@viewfly/router 2.1.0 → 3.0.0-alpha.0

package/README.md

@@ -1,132 +1,78 @@
-Viewfly
-================================
+# @viewfly/router
 
-Viewfly 是一个简单、数据驱动的前端框架。此项目为 Viewfly 的路由库，可让 Viewfly 支持浏览器路由。
+基于 **Viewfly** 的浏览器端路由：声明式链接、嵌套路由出口、编程式导航等。需配合 **`@viewfly/core`** 与 **`@viewfly/platform-browser`** 使用。
+
+---
 
 ## 安装
 
+```bash
+pnpm add @viewfly/router @viewfly/platform-browser @viewfly/core
 ```
-npm install @viewfly/router
-```
-
-## 使用示例
 
-```jsx
-import { createApp } from '@viewfly/platform-browser'
-import { RouterModule } from '@viewfly/router'
-
-function ListTab1() {
-  return () => {
-    return (
-      <div>listTab1</div>
-    )
-  }
-}
+---
 
-function ListTab2() {
-  return () => {
-    return (
-      <div>listTab2</div>
-    )
-  }
-}
+## 接入应用
 
-function ListTab3() {
-  return () => {
-    return (
-      <div>listTab3</div>
-    )
-  }
-}
+1. 使用 **`RouterModule`** 作为应用级扩展（通过 `createApp(...).use(...)` 注册）。
+2. 在布局中用 **`Link`** 生成导航，用 **`RouterOutlet`** 根据配置渲染匹配到的组件。
+3. 在组件内通过 **`inject(Router)`** 拿到路由实例，调用 **`navigateTo`** 等方法做跳转。
 
-function List() {
-  return () => {
-    return (
-      <div>
-        <h3>list</h3>
-        <div>
-          <Link active="active" to='./tab1'>tab1</Link>
-          <Link active="active" to='./tab2'>tab2</Link>
-          <Link active="active" to='./tab3'>tab3</Link>
-        </div>
-        <div>
-          <RouterOutlet config={[
-            {
-              name: 'tab1',
-              component: ListTab1
-            },
-            {
-              name: 'tab2',
-              component: ListTab2
-            },
-            {
-              name: 'tab3',
-              component: ListTab3
-            }
-          ]}>没找到 Tab</RouterOutlet>
-        </div>
-      </div>
-    )
-  }
-}
+最小串联示例（节选，完整路由表与懒加载等见官网）：
 
-function Detail() {
-  return () => {
-    return (
-      <div>detail</div>
-    )
-  }
-}
+```tsx
+import { inject } from '@viewfly/core'
+import { createApp } from '@viewfly/platform-browser'
+import { Link, Router, RouterModule, RouterOutlet } from '@viewfly/router'
 
 function Home() {
   const router = inject(Router)
-  return () => {
-    return (
-      <div>
-        <div>home</div>
-        <button type="button" onClick={() => {
-          router.navigateTo('../list')
-        }
-        }>跳转到列表
-        </button>
-      </div>
-    )
-  }
+  return () => (
+    <div>
+      <p>Home</p>
+      <button type="button" onClick={() => router.navigateTo('/list')}>去列表</button>
+    </div>
+  )
+}
+
+function List() {
+  return () => <div>List</div>
 }
 
 function App() {
-  return () => {
-    return (
-      <div>
-        <div>
-          <Link active="active" exact to="/">Home</Link>
-          <Link active="active" to="/list" queryParams={{ a: 'xx' }}>List</Link>
-          <Link active="active" to="/detail">Detail</Link>
-        </div>
-        <div>
-          <RouterOutlet config={[
-            {
-              name: 'home',
-              component: Home
-            },
-            {
-              name: 'list',
-              asyncComponent: () => Promise.resolve().then(() => List)
-            },
-            {
-              name: 'detail',
-              component: Detail
-            }
-          ]}>
-            未匹配到任何路由
-          </RouterOutlet>
-        </div>
-      </div>
-    )
-  }
+  return () => (
+    <div>
+      <nav>
+        <Link active="active" exact to="/">Home</Link>
+        <Link active="active" to="/list">List</Link>
+      </nav>
+      <RouterOutlet
+        config={[
+          { name: 'home', component: Home },
+          { name: 'list', component: List }
+        ]}
+      >
+        未匹配到路由
+      </RouterOutlet>
+    </div>
+  )
 }
 
-createApp(<App/>)use(new RouterModule()).mount(document.getElementById('app')!)
+createApp(<App />)
+  .use(new RouterModule())
+  .mount(document.getElementById('app')!)
 ```
 
-完整文档请参考官方网站：[viewfly.org](https://viewfly.org)
+**嵌套路由**：在子页面组件内再次放置 `RouterOutlet`，并为其传入子级 `config`（与官网「路由」章节一致）。
+
+---
+
+## 文档
+
+- **官方文档**：[viewfly.org](https://viewfly.org)
+
+---
+
+## License
+
+MIT

package/dist/hooks/_api.d.ts

@@ -0,0 +1 @@
+export * from './use-query-params';

package/dist/hooks/use-query-params.d.ts

@@ -0,0 +1,2 @@
+import { UrlQueryParams } from '../providers/url-parser';
+export declare function useQueryParams<T extends UrlQueryParams>(): T;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './hooks/_api';
+export * from './providers/_api';
+export * from './link';
+export * from './router-module';
+export * from './router-outlet';

package/dist/index.esm.js

@@ -0,0 +1,479 @@
+import { Injectable, comparePropsWithCallbacks, createContext, inject, internalWrite, jsx, makeError, onUnmounted, reactive, readonlyProxyHandler, shallowReactive } from "@viewfly/core";
+import { Subject, Subscription, fromEvent } from "@tanbo/stream";
+//#region src/providers/router.ts
+var routerErrorFn$1 = makeError("Router");
+var Router = class {
+	onRefresh;
+	get deep() {
+		return this.parent ? this.parent.deep + 1 : 0;
+	}
+	get path() {
+		return this.navigator.urlTree.paths.at(this.deep) || "";
+	}
+	refreshEvent = new Subject();
+	constructor(navigator, parent) {
+		this.navigator = navigator;
+		this.parent = parent;
+		this.onRefresh = this.refreshEvent.asObservable();
+	}
+	navigateTo(path, params, fragment) {
+		this.navigator.to(path, this, params, fragment || void 0);
+	}
+	replaceTo(path, params) {
+		this.navigator.replace(path, this, params);
+	}
+	refresh() {
+		this.refreshEvent.next();
+	}
+	consumeConfig(routes) {
+		return this.matchRoute(routes, this.path);
+	}
+	back() {
+		this.navigator.back();
+	}
+	forward() {
+		this.navigator.forward();
+	}
+	go(offset) {
+		this.navigator.go(offset);
+	}
+	matchRoute(configs, pathname) {
+		let matchedConfig = null;
+		let defaultConfig = null;
+		let fallbackConfig = null;
+		for (const item of configs) if (item.path === pathname) {
+			matchedConfig = item;
+			break;
+		} else if (item.path === "*") {
+			if (!fallbackConfig) fallbackConfig = item;
+		} else if (item.path === "") {
+			if (!defaultConfig) defaultConfig = item;
+		}
+		const config = matchedConfig || defaultConfig || fallbackConfig;
+		if (!config) return config;
+		if (typeof config.redirectTo === "function") {
+			const p = config.redirectTo(pathname);
+			if (typeof p === "string") this.navigateTo(p);
+			else if (typeof p === "object") this.navigateTo(p.pathname, p.queryParams, p.fragment);
+			else throw routerErrorFn$1(`Router redirect to '${pathname}' not supported`);
+			return null;
+		}
+		if (typeof config.redirectTo === "string") {
+			this.navigateTo(config.redirectTo);
+			return null;
+		}
+		return config;
+	}
+};
+//#endregion
+//#region src/providers/url-parser.ts
+var UrlParser = class {
+	index = 0;
+	url = "";
+	tokens = [];
+	parse(url) {
+		this.index = 0;
+		this.url = url;
+		this.tokens = [];
+		while (this.index < this.url.length) {
+			this.ignore("/");
+			if (this.peek("../")) {
+				this.tokens.push({ type: "toParent" });
+				this.index += 3;
+			} else if (this.peek("?")) {
+				this.index++;
+				this.tokens.push({
+					type: "query",
+					params: this.readQuery()
+				});
+			} else if (this.peek("#")) {
+				this.index++;
+				this.tokens.push({
+					type: "hash",
+					value: this.readHash()
+				});
+			} else {
+				if (this.peek("./")) this.index += 2;
+				const path = this.readPath();
+				if (path) this.tokens.push({
+					type: "toChild",
+					value: path
+				});
+			}
+		}
+		const urlTree = {
+			paths: [],
+			queryParams: {},
+			hash: null
+		};
+		for (const item of this.tokens) switch (item.type) {
+			case "toParent":
+				urlTree.paths.pop();
+				break;
+			case "toChild":
+				urlTree.paths.push(item.value);
+				break;
+			case "query":
+				urlTree.queryParams = item.params;
+				break;
+			case "hash": urlTree.hash = item.value;
+		}
+		return urlTree;
+	}
+	readHash() {
+		const hash = this.url.substring(this.index);
+		this.index = this.url.length;
+		return hash;
+	}
+	readQuery() {
+		const query = {};
+		while (this.index < this.url.length) {
+			const key = this.readQueryKey();
+			let value = "";
+			if (this.peek("=")) {
+				this.index++;
+				value = this.readQueryValue();
+			}
+			const oldValue = query[key];
+			if (oldValue) if (Array.isArray(oldValue)) oldValue.push(value);
+			else query[key] = [oldValue, value];
+			else query[key] = value;
+			if (this.peek("&")) {
+				this.index++;
+				continue;
+			}
+			break;
+		}
+		return query;
+	}
+	readQueryValue() {
+		const chars = [];
+		while (this.index < this.url.length) {
+			if (this.not("&#")) {
+				chars.push(this.url.at(this.index));
+				this.index++;
+				continue;
+			}
+			break;
+		}
+		return chars.join("");
+	}
+	readQueryKey() {
+		const chars = [];
+		while (this.index < this.url.length) {
+			if (this.not("=&#")) {
+				chars.push(this.url.at(this.index));
+				this.index++;
+				continue;
+			}
+			break;
+		}
+		return chars.join("");
+	}
+	readPath() {
+		const chars = [];
+		while (this.index < this.url.length) {
+			if (this.not("./?#")) {
+				chars.push(this.url.at(this.index));
+				this.index++;
+				continue;
+			}
+			break;
+		}
+		return chars.join("");
+	}
+	not(text) {
+		const ch = this.url.at(this.index);
+		return text.indexOf(ch) === -1;
+	}
+	peek(str) {
+		return this.url.slice(this.index, this.index + str.length) === str;
+	}
+	ignore(str) {
+		while (this.peek(str)) this.index++;
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.126.0/helpers/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.126.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/providers/navigator.ts
+var Navigator = class {
+	constructor(baseUrl) {
+		this.baseUrl = baseUrl;
+	}
+};
+function formatUrl(pathname, urlFormatParams) {
+	pathname = pathname.replace(/\/+/g, "/");
+	const { queryParams, fragment } = urlFormatParams;
+	return pathname + (queryParams ? "?" + formatQueryParams(queryParams) : "") + (fragment ? "#" + fragment : "");
+}
+function formatQueryParams(queryParams) {
+	const params = [];
+	Object.keys(queryParams).forEach((key) => {
+		const values = queryParams[key];
+		if (Array.isArray(values)) values.forEach((i) => {
+			params.push(`${key}=${decodeURIComponent(i)}`);
+		});
+		else params.push(`${key}=${decodeURIComponent(values)}`);
+	});
+	return params.join("&");
+}
+var BrowserNavigator = class BrowserNavigator extends Navigator {
+	onUrlChanged;
+	/** 挂载在 location 上的路径前缀；'' 或 '/' 表示站点根，不做剥离 */
+	get basePathPrefix() {
+		return this.baseUrl === "/" || this.baseUrl === "" ? "" : this.baseUrl;
+	}
+	get pathname() {
+		const pathname = location.pathname;
+		if (!this.basePathPrefix) return pathname;
+		return pathname.startsWith(this.basePathPrefix) ? pathname.substring(this.basePathPrefix.length) : pathname;
+	}
+	urlParser = new UrlParser();
+	urlTree = this.getUrlTree();
+	urlChangeEvent = new Subject();
+	subscription = new Subscription();
+	constructor(baseUrl, hooks = {}) {
+		super(baseUrl);
+		this.hooks = hooks;
+		this.onUrlChanged = this.urlChangeEvent.asObservable();
+		this.subscription.add(fromEvent(window, "popstate").subscribe(() => {
+			this.urlTree = this.getUrlTree();
+			this.urlChangeEvent.next();
+		}));
+		if (this.basePathPrefix && !location.pathname.startsWith(this.basePathPrefix)) history.replaceState(null, "", this.baseUrl);
+	}
+	to(pathName, relative, queryParams, fragment) {
+		const url = this.join(pathName, relative, queryParams, fragment);
+		if (location.origin + url === location.href) return true;
+		this.runHooks({
+			pathname: this.pathname,
+			queryParams: this.urlTree.queryParams,
+			fragment: this.urlTree.hash
+		}, {
+			pathname: pathName,
+			queryParams: queryParams || {},
+			fragment: fragment || null
+		}, () => {
+			history.pushState(null, "", url);
+			this.urlTree = this.getUrlTree();
+			this.urlChangeEvent.next();
+		});
+		return true;
+	}
+	replace(pathName, relative, queryParams, fragment) {
+		const url = this.join(pathName, relative, queryParams, fragment);
+		if (location.origin + url === location.href) return true;
+		this.runHooks({
+			pathname: this.pathname,
+			queryParams: this.urlTree.queryParams,
+			fragment: this.urlTree.hash
+		}, {
+			pathname: pathName,
+			queryParams: queryParams || {},
+			fragment: fragment || null
+		}, () => {
+			history.replaceState(null, "", url);
+			this.urlTree = this.getUrlTree();
+			this.urlChangeEvent.next();
+		});
+		return true;
+	}
+	join(pathname, relative, queryParams, fragment) {
+		if (pathname.startsWith("/")) return formatUrl(this.baseUrl + pathname, {
+			queryParams,
+			fragment
+		});
+		const beforePath = this.urlTree.paths.slice(0, relative.deep);
+		while (true) {
+			if (pathname.startsWith("./")) {
+				pathname = pathname.substring(2);
+				continue;
+			}
+			if (pathname.startsWith("../")) {
+				pathname = pathname.substring(3);
+				beforePath.pop();
+				continue;
+			}
+			break;
+		}
+		return formatUrl(this.baseUrl + "/" + beforePath.join("/") + "/" + pathname, {
+			queryParams,
+			fragment
+		});
+	}
+	back() {
+		history.back();
+	}
+	forward() {
+		history.forward();
+	}
+	go(offset) {
+		history.go(offset);
+	}
+	destroy() {
+		this.subscription.unsubscribe();
+	}
+	runHooks(beforeParams, currentParams, next) {
+		if (typeof this.hooks.beforeEach === "function") this.hooks.beforeEach?.(beforeParams, currentParams, () => {
+			next();
+			this.hooks.afterEach?.(currentParams);
+		});
+		else {
+			next();
+			this.hooks.afterEach?.(currentParams);
+		}
+	}
+	getUrlTree() {
+		return this.urlParser.parse(this.pathname + location.search + location.hash);
+	}
+};
+BrowserNavigator = __decorate([Injectable(), __decorateMetadata("design:paramtypes", [String, Object])], BrowserNavigator);
+//#endregion
+//#region src/hooks/use-query-params.ts
+function useQueryParams() {
+	const router = inject(Router);
+	const navigator = inject(Navigator);
+	const params = { ...navigator.urlTree.queryParams };
+	const queryParams = new Proxy(params, readonlyProxyHandler);
+	const subscription = router.onRefresh.subscribe(() => {
+		comparePropsWithCallbacks(params, navigator.urlTree.queryParams, (key) => {
+			internalWrite(() => {
+				Reflect.deleteProperty(params, key);
+			});
+		}, (key, value) => {
+			internalWrite(() => {
+				params[key] = value;
+			});
+		}, (key, value) => {
+			internalWrite(() => {
+				params[key] = value;
+			});
+		});
+	});
+	onUnmounted(() => {
+		subscription.unsubscribe();
+	});
+	return queryParams;
+}
+//#endregion
+//#region src/link.tsx
+function Link(props) {
+	const navigator = inject(Navigator);
+	const router = inject(Router);
+	function getActive() {
+		return props.exact ? navigator.pathname === navigator.join(props.to, router) || navigator.pathname + "/" === navigator.join(props.to, router) : navigator.pathname.startsWith(navigator.join(props.to, router));
+	}
+	const isActive = reactive({ value: getActive() });
+	const subscription = navigator.onUrlChanged.subscribe(() => {
+		isActive.value = getActive();
+	});
+	onUnmounted(() => {
+		subscription.unsubscribe();
+	});
+	function navigate(ev) {
+		if ((!props.tag || props.tag === "a") && props.target === "_blank") return;
+		ev.preventDefault();
+		router.navigateTo(props.to, props.queryParams, props.fragment);
+	}
+	return () => {
+		const Tag = props.tag || "a";
+		const attrs = Object.assign({}, props, {
+			onClick(ev) {
+				navigate(ev);
+				props.onClick?.(ev);
+			},
+			...props
+		});
+		if (Tag === "a") attrs.href = navigator.join(props.to, router, props.queryParams, props.fragment);
+		if (isActive.value && props.active) attrs.class = [attrs.class, props.active];
+		return /* @__PURE__ */ jsx(Tag, {
+			...attrs,
+			children: props.children
+		});
+	};
+}
+//#endregion
+//#region src/router-module.ts
+var RouterModule = class {
+	subscription = new Subscription();
+	navigator;
+	constructor(baseUrl = "", hooks = {}) {
+		this.baseUrl = baseUrl;
+		this.navigator = new BrowserNavigator(this.baseUrl, hooks);
+	}
+	setup(app) {
+		const navigator = this.navigator;
+		const router = new Router(navigator, null);
+		this.subscription.add(navigator.onUrlChanged.subscribe(() => {
+			router.refresh();
+		}));
+		app.provide([{
+			provide: Navigator,
+			useValue: navigator
+		}, {
+			provide: Router,
+			useValue: router
+		}]);
+	}
+	onDestroy() {
+		this.subscription.unsubscribe();
+		this.navigator.destroy();
+	}
+};
+//#endregion
+//#region src/router-outlet.tsx
+var routerErrorFn = makeError("RouterOutlet");
+function RouterOutlet(props) {
+	const router = inject(Router, null);
+	if (router === null) throw routerErrorFn("cannot found parent Router.");
+	const childRouter = new Router(inject(Navigator), router);
+	const Context = createContext([{
+		provide: Router,
+		useValue: childRouter
+	}]);
+	const children = shallowReactive({ value: null });
+	const subscription = router.onRefresh.subscribe(() => {
+		updateChildren();
+	});
+	onUnmounted(() => {
+		subscription.unsubscribe();
+	});
+	let currentComponent = null;
+	async function updateChildren() {
+		const routeConfig = router.consumeConfig(props.config);
+		if (!routeConfig) {
+			currentComponent = null;
+			children.value = props.children || null;
+			return;
+		}
+		if (typeof routeConfig.beforeEach === "function") {
+			if (!await routeConfig.beforeEach()) return;
+		}
+		if (routeConfig.component) _updateChildren(routeConfig.component);
+		else if (routeConfig.asyncComponent) _updateChildren(await routeConfig.asyncComponent());
+		if (typeof routeConfig.afterEach === "function") routeConfig.afterEach();
+	}
+	function _updateChildren(Component) {
+		childRouter.refresh();
+		if (Component !== currentComponent) children.value = /* @__PURE__ */ jsx(Component, {});
+		currentComponent = Component;
+	}
+	updateChildren();
+	return () => {
+		return /* @__PURE__ */ jsx(Context, { children: children.value });
+	};
+}
+//#endregion
+export { BrowserNavigator, Link, Navigator, Router, RouterModule, RouterOutlet, UrlParser, formatQueryParams, formatUrl, useQueryParams };