amateras 0.10.0 → 0.10.2

package/packages/prefetch/src/index.ts

@@ -0,0 +1,70 @@
+import { onclient, onserver } from "@amateras/core";
+import { GlobalState } from "@amateras/core";
+import { Proto } from "@amateras/core";
+import { _null, _Object_assign, isAsyncFunction, toURL } from "@amateras/utils";
+
+declare global {
+    export namespace $ {
+        export function fetch<T = any>(url: string | URL, options?: RequestInit & FetchOptions<T>): Promise<T>
+    }
+    export var prefetch: {[key: string]: { expired: number, data: any }}
+}
+
+declare module "@amateras/core" {
+    export interface GlobalState {
+        prefetch: {
+            fetches: Set<Promise<any>>,
+            caches: {[key: string]: { expired: number, data: any }}
+        }
+    }
+}
+
+export type FetchOptions<T> = {
+    record?: (res: Response) => Promise<T> | void;
+    then?: (result: T) => void;
+}
+
+_Object_assign(GlobalState.prototype, {
+    prefetch: {
+        fetches: new Set(),
+        caches: {}
+    }
+})
+
+GlobalState.disposers.add(global => {
+    global.prefetch.fetches.clear();
+})
+
+if (!globalThis.prefetch) globalThis.prefetch = {}
+
+_Object_assign($, {
+    // 将资料注册到原型全局变量中：global.prefetch
+    // 保证每次全局渲染都在抓取完毕之后：将 Promise 添加到 global.prefetch.fetches 让根原型能确保所有 fetch 运行结束
+    // 将已抓取的资料发送到客户端：从 record 函数回传的资料将会被记录在 global.prefetch.caches 当中，并且以抓取 URL 作为索引。
+    // 客户端不会用到过时的资料：每个发送到客户端的资料缓存都附上了过期时间
+    async fetch<T>(url: string | URL, options?: RequestInit & FetchOptions<T>) {
+        url = toURL(url);
+        let proto = Proto.proto;
+        let cache = onclient() ? prefetch[url.href] : _null;
+        let then = options?.then;
+        let request = new Promise(async (resolve) => {
+            if (cache && Date.now() < cache.expired) {
+                then?.(cache.data);
+                resolve(cache);
+                return;
+            }
+            let response = await fetch(url, options);
+            let record = options?.record;
+            if (record) {
+                const result = isAsyncFunction(record) ? await record(response) : record(response);
+                if (onserver() && proto) proto.global.prefetch.caches[url.href] = { data: result, expired: Date.now() + 30_000 };
+                $.context(Proto, proto, () => {
+                    then?.(result);
+                })
+                resolve(result);
+            }
+        })
+        if (onserver()) proto?.global.prefetch.fetches.add(request)
+        return request
+    }
+})

package/packages/router/README.md

@@ -0,0 +1,18 @@
+# Amateras Router
+Router 是实现路由的标准模块，使用此模块就能轻松规划页面路径。
+
+## 优势
+- 路径参数类型保护
+- 页面路径别名机制
+- 路径分组功能
+- 组件化页面
+
+## 使用方式
+使用 `$.router` 函数定义路由构造器（Router Constructor）。
+```ts
+import 'amateras';
+import 'amateras/router';
+```
+
+## 文档
+[路由器](/docs/Router.md)

package/packages/router/package.json

@@ -0,0 +1,16 @@
+{
+    "name": "@amateras/router",
+    "peerDependencies": {
+      "@amateras/core": "workspace:*",
+      "@amateras/widget": "workspace:*",
+      "@amateras/utils": "workspace:*"
+    },
+    "imports": {
+      "#structure/*": "./src/structure/*.ts",
+      "#lib/*": "./src/lib/*.ts",
+      "#node/*": "./src/node/*.ts"
+    },
+    "exports": {
+      ".": "./src/index.ts"
+    }
+}

package/packages/router/src/global.ts

@@ -0,0 +1,22 @@
+import * as _Link from "#structure/Link";
+import * as _NavLink from "#structure/NavLink";
+import * as _Router from "#structure/Router";
+import type { Router, RouterHandle } from "#structure/RouterConstructor";
+
+declare global {
+    export var Link: typeof _Link.Link;
+    export var NavLink: typeof _NavLink.NavLink;
+    export function $(Router: Router): _Router.RouterProto;
+
+    export namespace $ {
+        export function router(handle: RouterHandle): Router;
+
+        export function open(path: string, target?: string): void;
+        export function forward(): void;
+        export function back(): void;
+        export function replace(path: string): void;
+        export function scrollRestoration(): void;
+
+        export function title(title: string): void;
+    }
+}

package/packages/router/src/index.ts

@@ -0,0 +1,106 @@
+import { Link } from '#structure/Link';
+import { NavLink } from '#structure/NavLink';
+import { Page } from '#structure/Page';
+import { Route } from '#structure/Route';
+import { RouteGroup } from '#structure/RouteGroup';
+import { RouteNode } from '#structure/RouteNode';
+import { RouterProto } from '#structure/Router';
+import { RouterConstructor } from '#structure/RouterConstructor';
+import { symbol_ProtoType } from '@amateras/core';
+import { GlobalState } from '@amateras/core';
+import { Proto } from '@amateras/core';
+import { _instanceof, _Object_assign, isFunction, map } from '@amateras/utils';
+import './global';
+import type { PageLayout } from './types';
+
+declare module "@amateras/core" {
+    export interface GlobalState {
+        title: string | null
+        router: {
+            routers: Set<RouterProto>;
+            resolve: (path: string) => Promise<void>[];
+            href: URL;
+            routes: Route[];
+            matchPaths: string[];
+            navlinks: Set<NavLink>;
+        }
+    }
+}
+
+let routePlannerPrototype = {
+    route(this: Route | RouterProto, path: string, layout: PageLayout<string>, handle?: (route: Route) => void) {
+        let route = new RouteNode(path, layout);
+        this.routes.set(path, route);
+        handle?.(route);
+    },
+
+    group(this: Route | RouterProto, path: string, handle?: (route: Route) => void) {
+        let group = new RouteGroup(path);
+        this.routes.set(path, group);
+        handle?.(group);
+    },
+
+    notfound() {
+
+    }
+}
+
+_Object_assign(Route.prototype, routePlannerPrototype);
+_Object_assign(RouterProto.prototype, routePlannerPrototype);
+_Object_assign(GlobalState.prototype, {
+    router: {
+        routers: new Set<RouterProto>(),
+        resolve(this, path: string) {
+            return map(this.routers, router => router.resolve(path));
+        },
+        href: new URL('http://localhost'),
+        routes: [],
+        matchPaths: [],
+        navlinks: new Set()
+    }
+})
+
+GlobalState.disposers.add(({router}) => {
+    router.routers.clear();
+    router.routes = [];
+    router.matchPaths = [];
+    router.navlinks.clear();
+})
+
+_Object_assign($, {
+    router: (handle: ($$: RouterProto) => void) => RouterConstructor(handle),
+    open: RouterProto.open,
+    replace: RouterProto.replace,
+    back: RouterProto.back,
+    forward: RouterProto.forward,
+    scrollRestoration: RouterProto.scrollRestoration,
+
+    title(title: string) {
+        let parent = Proto.proto;
+        if (_instanceof(parent, Page)) {
+            parent.title = title;
+        }
+    }
+})
+
+globalThis.Link = Link;
+globalThis.NavLink = NavLink;
+
+$.process.craft.add((value) => {
+    if (isFunction(value) && value[symbol_ProtoType] === 'Router') {
+        let proto = Proto.proto;
+        let router = new value() as RouterProto;
+        proto?.global.router.routers.add(router);
+        router.parent = proto;
+        return router;
+    }
+})
+
+export * from "#structure/Link";
+export * from "#structure/Page";
+export * from "#structure/Route";
+export * from "#structure/RouteGroup";
+export * from "#structure/RouteNode";
+export * from "#structure/Router";
+export * from "#structure/RouteSlot";
+

package/packages/router/src/structure/Link.ts

@@ -0,0 +1,17 @@
+import { ElementProto } from "@amateras/core";
+
+export class Link extends ElementProto<HTMLAnchorElement> {
+    constructor(attr: $.Props | null, layout?: $.Layout<ElementProto<HTMLAnchorElement>>) {
+        super('a', attr, layout);
+        this.on('click', e => {
+            if (e.shiftKey || e.ctrlKey) return;
+            e.preventDefault();
+            let target = this.attr('target');
+            let href = this.attr('href');
+            if (href) {
+                if (target === '_replace') $.replace(href) 
+                else $.open(href, target)
+            }
+        })
+    }
+}

package/packages/router/src/structure/NavLink.ts

@@ -0,0 +1,19 @@
+import { Link } from "#structure/Link";
+import type { ElementProto } from "@amateras/core";
+import { _null, toURL } from "@amateras/utils";
+
+export class NavLink extends Link {
+    constructor(attr: $.Props | null, layout?: $.Layout<ElementProto<HTMLAnchorElement>>) {
+        super(attr, layout);
+        this.global.router.navlinks.add(this);
+    }
+
+    checkActive() {
+        let href = this.attr('href');
+        if (!href) return;
+        for (let path of this.global.router.matchPaths) {
+            if (toURL(path).href === toURL(href).href) return this.attr('active', ''); 
+        }
+        this.attr('active', _null);
+    }
+}

package/packages/router/src/structure/Page.ts

@@ -0,0 +1,30 @@
+import { Proto } from "@amateras/core";
+import { _null } from "@amateras/utils";
+import type { AsyncWidget, PageLayout } from "../types";
+import type { RouteNode } from "./RouteNode";
+import { RouteSlot } from "./RouteSlot";
+
+export class Page extends Proto {
+    slot = new RouteSlot();
+    builded = false;
+    route: RouteNode;
+    title: string | null = _null;
+    declare layout: () => void | AsyncWidget[0];
+    constructor(route: RouteNode, layout: PageLayout, params: Record<string, string>) {
+        super(() => layout({
+            params,
+            slot: this.slot
+        }));
+        this.route = route;
+    }
+
+    override build() {
+        if (!this.builded) this.builded = true;
+        return super.build();
+    }
+}
+
+export interface Page {
+    get parent(): RouteSlot;
+    set parent(proto: Proto);
+}

package/packages/router/src/structure/Route.ts

@@ -0,0 +1,123 @@
+import { _undefined, isFunction, isUndefined, map } from "@amateras/utils";
+import type { Widget } from "@amateras/widget";
+import type { AliasRequired, AsyncWidget, PageLayout, PathConcat, PathToParamsMap, RouteParams, RoutePath, ValidatePath } from "../types";
+import type { Page } from "./Page";
+import type { RouteSlot } from "./RouteSlot";
+
+
+export abstract class Route<ParentPath extends RoutePath = any, Path extends RoutePath = any, Params = any> {
+    declare protos: Set<Page | Route>;
+    declare parentPath: ParentPath;
+    declare params: Params;
+    routes = new Map<string, Route>();
+    path: string;
+    paths = new Map<string, RouteParams | (() => RouteParams) | undefined>();
+    validPaths: string[] = []
+    constructor(path: Path) {
+        this.path = path;
+        this.paths.set(path, _undefined);
+    }
+
+    abstract resolve(path: string, slot: RouteSlot, params: Record<string, string>): Promise<Route[] | void>;
+
+    routing(path: string) {
+        let pathSegList = path.split('/');
+        let params: Record<string, string> = {};
+        let passPath = '';
+
+        skipPath: for (let [selfPath, getParams] of this.paths) {
+            params = {};
+            let selfSegList = selfPath.split('/');
+            let segList: [string | undefined, string | undefined][] = [];
+
+            for (let i = 0; i < Math.max(pathSegList.length, selfSegList.length); i++) 
+                segList.push([selfSegList[i], pathSegList[i]])
+
+            skipSeg: for (let [selfSeg, pathSeg] of segList) {
+                let skip = () => {
+                    passPath = '';
+                }
+                let pass = () => {
+                    passPath += (passPath !== '/' ? '/' : '') + pathSeg;
+                }
+                if (isUndefined(selfSeg)) {
+                    // all path segment matched;
+                    break skipSeg;
+                }
+                if (isUndefined(pathSeg)) {
+                    // this route path is longer than target path;
+                    skip();
+                    continue skipPath;
+                }
+                
+                if (selfSeg?.includes(':')) {
+                    let [prefix, name] = selfSeg.split(':') as [string, string];
+                    if (!pathSeg.startsWith(prefix)) {
+                        skip();
+                        continue skipPath;
+                    }
+                    // path params
+                    params[name] = pathSeg.replace(prefix, '');
+                    pass();
+                    continue skipSeg;
+                }
+
+                if (selfSeg !== pathSeg) {
+                    // this segment not matched
+                    skip();
+                    continue skipPath;
+                }
+                pass();
+            }
+            if (!passPath) continue skipPath;
+            params = {...params, ...isFunction(getParams) ? getParams() : getParams}
+            break skipPath;
+        }
+        
+        if (!passPath) return;
+        let pathId = Route.resolvePath(this.path, params);
+        this.validPaths = map(this.paths, path => Route.resolvePath(path[0], params));
+        return [pathId, passPath, params] as const
+    }
+
+    private static resolvePath(path: string, params: any) {
+        return path.replaceAll(/:([^/]+)/g, (_, $1) => `${params[$1]}`);
+    }
+
+    alias<
+        _Path extends RoutePath,
+        _Params extends AliasRequired<Params, PathToParamsMap<_Path>>,
+        Required extends keyof _Params extends [never] ? [] : [_Params | (() => _Params)]
+    >(path: _Path, ...required: Required): void;
+    alias(path: string, required?: RouteParams | (() => RouteParams)) {
+        this.paths.set(path, required)
+    }
+}
+
+export interface Route<ParentPath extends RoutePath = any, Path extends RoutePath = any, Params = any> {
+
+    
+    route<_Path extends string, Props>(
+        path: ValidatePath<_Path, Props, PathConcat<ParentPath, Path, _Path>>,
+        widget: Widget<any, Props>,
+        handle?: (route: Route<PathConcat<ParentPath, Path>, _Path, PathToParamsMap<PathConcat<Path, _Path>>>) => void): void
+
+    route<_Path extends string, Props>(
+        path: ValidatePath<_Path, Props, PathConcat<ParentPath, Path, _Path>>,
+        widget: AsyncWidget<Props>,
+        handle?: (route: Route<PathConcat<ParentPath, Path>, _Path, PathToParamsMap<PathConcat<Path, _Path>>>) => void): void
+
+    route<
+        _Path extends RoutePath,
+        Layout extends PageLayout<PathConcat<ParentPath, Path, _Path>>
+    >(path: _Path, layout: Layout, handle?: (route: Route<PathConcat<ParentPath, Path>, _Path, PathToParamsMap<PathConcat<Path, _Path>>>) => void): void
+
+    group<
+        _Path extends RoutePath
+    >(path: _Path, handle: (route: Route<ParentPath, _Path, PathToParamsMap<PathConcat<Path, _Path>>>) => void): this;
+
+}
+
+
+
+

package/packages/router/src/structure/RouteGroup.ts

@@ -0,0 +1,24 @@
+import { Route } from "./Route";
+import type { RouteSlot } from "./RouteSlot";
+
+export class RouteGroup extends Route {
+    constructor(path: string) {
+        super(path);
+    }
+    
+    async resolve(path: string, slot: RouteSlot, params: Record<string, string>): Promise<Route[] | void> {
+        let result = this.routing(path);
+        if (!result) return;
+        let [, passPath, selfParams] = result;
+
+        params = {...params, ...selfParams};
+        let restPath = path.replace(passPath, '');
+        // handler '/' at path end
+
+        for (let [_name, route] of this.routes) {
+            let result = await route.resolve(restPath || '/', slot, params)
+            if (result) return [this, ...result];
+        }
+        return [this];
+    }
+}

package/packages/router/src/structure/RouteNode.ts

@@ -0,0 +1,54 @@
+import { symbol_ProtoType } from "@amateras/core";
+import { _null, isArray } from "@amateras/utils";
+import type { Widget } from "@amateras/widget";
+import type { AsyncWidget, PageLayout } from "../types";
+import { Page } from "./Page";
+import { Route } from "./Route";
+import type { RouteSlot } from "./RouteSlot";
+
+export class RouteNode extends Route {
+    pages = new Map<string, Page>();
+    page: Page | null = _null;
+    #layout: Widget | PageLayout | AsyncWidget;
+    constructor(path: string, layout: Widget | PageLayout | AsyncWidget) {
+        super(path);
+        this.#layout = layout;
+    }
+
+    async resolve(path: string, slot: RouteSlot, params: Record<string, string>): Promise<Route[] | void> {
+        let result = this.routing(path);
+        if (!result) return;
+        let [pathId, passPath, selfParams] = result;
+        params = { ...params, ...selfParams };
+        let page = await this.usePage(pathId, params, slot);
+        let restPath = path.replace(passPath, '');
+        for (let [_name, route] of this.routes) {
+            let result = await route.resolve(restPath || '/', page.slot, params)
+            if (result) return [this, ...result];
+        }
+        if (!restPath) return [this];
+        return;
+    }
+
+    async usePage(path: string, params: Record<string, string>, slot: RouteSlot) {
+        let page = this.pages.get(path);
+        if (!page) {
+            let layout = this.#layout;
+            let _layout;
+            if (isArray(layout)) {
+                let widget = await layout[0]().then(mod => mod.default);
+                _layout = () => $(widget, params, () => $(page!.slot));
+            } else {
+                //@ts-ignore
+                _layout = this.#layout[symbol_ProtoType] === 'Widget' // is widget constructor
+                ?   () => $(this.#layout as Widget, params, () => $(page!.slot)) 
+                :   this.#layout as PageLayout;
+            }
+            page = new Page(this, _layout, params);
+            this.pages.set(path, page);
+        }
+        this.page = page;
+        slot.render(page);
+        return page;
+    }
+}

package/packages/router/src/structure/RouteSlot.ts

@@ -0,0 +1,34 @@
+import { onserver } from "@amateras/core";
+import { ProxyProto } from "@amateras/core";
+import { _null } from "@amateras/utils";
+import type { Page } from "./Page";
+
+export class RouteSlot extends ProxyProto {
+    page: Page | null = _null;
+    constructor() {
+        super();
+    }
+
+    render(page: Page) {
+        if (this.page === page) return;
+        this.clear();
+        this.layout = () => $(page);
+        page.parent = this;
+        if (this.page !== page) this.page?.removeNode();
+        this.page = page;
+        if (this.node) {
+            if (!page.builded) page.build();
+            let nodes = this.toDOM();
+            this.node.replaceWith(...nodes);
+            // set title from page
+            if (page.title) {
+                document.title = page.title;
+                page.global.title = page.title;
+            }
+        }
+        if (onserver()) {
+            if (!page.builded) page.build();
+            page.global.title = page.title;
+        }
+    }
+}