amateras 0.5.0 → 0.6.0

package/ext/markdown/src/syntax/table.ts

@@ -0,0 +1,67 @@
+import { BLOCK, TABLE, TABLE_COLUMN, TABLE_ROW } from "#lib/type";
+import { htmltag, setBlockTokenizer, setProcessor } from "#lib/util";
+import type { BlockToken, MarkdownLexer } from "#structure/MarkdownLexer";
+import type { MarkdownParser } from "#structure/MarkdownParser";
+import { _Array_from } from "amateras/lib/native";
+
+export const tableProcessor = (parser: MarkdownParser) => setProcessor(parser, TABLE, (token) => {
+        let thead = '';
+        let tbody = '';
+        let rowIndex = 0;
+        for (const row of token.content!) {
+            let rowHTML = '';
+            for (let i = 0; i < row.content!.length; i++) {
+                const col = row.content![i]!;
+                const align = token.data!.align[i];
+                const tagname = rowIndex === 0 ? 'th' : 'td';
+                rowHTML += `<${tagname} align="${align ?? 'left'}">${parser.parse(col.content!)}</${tagname}>`
+            }
+            if (rowIndex === 0) thead += htmltag('thead', htmltag('tr', rowHTML));
+            else tbody += htmltag('tr', rowHTML);
+            rowIndex++
+        }
+        tbody = htmltag('tbody', tbody);
+        return htmltag('table', thead + tbody)
+    })
+
+export const tableTokenizer = (lexer: MarkdownLexer) => setBlockTokenizer(lexer, TABLE, {
+        regex: /\|(?:.+\|)+/,
+        handle(_, position, lines) {
+            const tokens: BlockToken[] = [];
+            const align = []
+            while (position < lines.length) {
+                const row: BlockToken = {
+                    type: TABLE_ROW,
+                    layout: BLOCK,
+                    content: []
+                }
+                const line = lines[position]!;
+                const matches = _Array_from(line.matchAll(/\| ([^|]+)/g));
+                if (!matches.length) break;
+                for (const match of matches) {
+                    const text = match[1]!;
+                    const separator = text.match(/(:)?---+(:)?/);
+                    if (separator) {
+                        const [_, LEFT, RIGHT] = separator;
+                        align.push(RIGHT ? LEFT ? 'center' : 'right' : 'left');
+                        continue;
+                    }
+                    row.content.push({
+                        type: TABLE_COLUMN,
+                        content: lexer.inlineTokenize(text.trim()),
+                        layout: BLOCK
+                    })
+                }
+                if (row.content.length) tokens.push(row);
+                position++
+            }
+            return {
+                content: tokens,
+                data: { align },
+                multiLine: {
+                    skip: position,
+                    tokens: []
+                }
+            }
+        },
+    })

package/ext/markdown/src/syntax/text.ts

@@ -0,0 +1,19 @@
+import { EMPTY_LINE, TEXT, TEXT_LINE } from "#lib/type";
+import { htmltag, setProcessor } from "#lib/util";
+import type { MarkdownParser } from "#structure/MarkdownParser";
+
+export const textProcessor = (parser: MarkdownParser) => setProcessor(parser, TEXT, token => token.text!);
+
+export const textLineProcessor = (parser: MarkdownParser) => setProcessor(parser, TEXT_LINE, (_, tokens) => {
+    let html = '';
+    let i = 0;
+    for (const token of tokens) {
+        if (token.type === EMPTY_LINE) break;
+        html += parser.parse(token.content!);
+        i++;
+    }
+    return {
+        html: htmltag('p', html),
+        skipTokens: i
+    };
+})

package/ext/router/README.md

@@ -9,8 +9,8 @@ import 'amateras/router';
 ## Create Route Map
 ```ts
 // create home page route
-const HomePage = $('route', '/', page => page
-    .pageTitle('Home')
+const HomePage = $.route(page => page
+    .pageTitle('Home | My Site') // set window title
     .content([
         $('h1').content('Home')
     ])
@@ -24,6 +24,9 @@ $(document.body).content([
 ])
 ```
 
+> [!NOTE]
+> Don't forget to `.listen()` the path change!
+
 ## Router Anchor
 Use `RouterAnchor` to prevent load page when open link by default `HTMLAnchorElement` element.
 ```ts
@@ -36,46 +39,137 @@ $('ra').content('Contact').href('/contact');
 - `$.forward()`: Forward page.
 - `$.back()`: Back page.
 
-## Path Parameter and Query
+## Async Route
+```ts
+// ./page/home_page.ts
+export default $.route(page => {
+    return page
+    .content([
+        $('h1').content('Home Page')
+    ])
+})
+
+// ./router.ts
+$('router')
+.route('/about', () => import('./page/home_page'))
+```
+
+## Path Parameter
+TypeScript will parse the parameter in the path, parameter always start with `:`, after the colon comes the name of the parameter. You can access theses parameter using `Page.params`.
+
 ```ts
 $('router')
 .route('/user/@:username', page => {
-    console.log(page.params)
+    console.log(page.params.username);
+    return page;
 })
-.route('/posts?search'), page => {
-    console.log(page.query)
-}
 .listen()
 // simulate page open
-.resolve('/user/@amateras') // { username: 'amateras' }
-.resolve('/posts"') // { }
-.resolve('/posts?search=tsukimi&user') // { search: 'tsukimi', user: '' }
+.resolve('/user/@amateras') // 'amateras'
+```
+
+If you want separate router and route builder to different file, use generic parameter to define parameter name on `$.route` method. 
+
+```ts
+// greating_page.ts
+export default $.route<['name']>(page => {
+    return page
+    .content(`Hello, ${name}`)
+})
+
+// router.ts
+$('router')
+.route('/greating', () => import('./greating_page'))
+// ^ typescript wiil report an error, the route builder required 'name' parameter
+
+.route('/greating/:name', () => import('./greating_page'))
+// ^ pass
+```
+
+### Optional Parameter
+Sometime we parameter can be optional, you can define the optional parameter by add `?` sign after the name of the parameter.
+
+```ts
+const userPage = $.route<'photoId', 'postId?'>(page => {
+    return page
+    .content([
+        `Photo ID: ${page.params.photoId}`, // photoId: string
+        `Post ID: ${page.params.postId}` // postId: string | undefined 
+    ])
+})
+
+$('router')
+.route('/photos/:photoId', userPage)
+// ^ pass
+.route('/posts/:postId/photos/:photoId', userPage)
+// ^ pass
 ```
 
 ## Nesting Route
+`Router` element is the container of `Page` element, we can archieve nesting route by create `Router` and append it inside `Page`.
 ```ts
-const ContactPage = $('route', '/contact', page => page
+const ContactPage = $.route(page => page
     .pageTitle('Home')
     .content([
         $('h1').content('Contact'),
-        // append router with page, nested routes will show in this router
-        $('router', page)
+        $('router', page) 
+        // here is the magic happened,
+        // pass the Page into router arguments
     ])
 )
+```
 
-const ContactEmailPage = $('route', '/contact/email', () => 'amateras@example.com')
+Then, we need to declare the router map like this: 
 
+```ts
 $('router')
 .route('/', HomePage)
 .route('/contact', ContactPage, route => route
+    // we can define more child routes inside this '/contact' route!
     .route('/', () => 'My name is Amateras.')
     .route('/phone', () => '0123456789')
-    .route('/email', ContactEmailPage)
 )
 ```
 
-## Async Route
+### Alias Path
+
+Sometime, the page doesn't have just one path. We can declare the alias paths to one route!
+
 ```ts
 $('router')
-.route('/about', () => import('./pages/about.ts'))
+.route('/', HomePage, route => route
+    .alias('/home')
+    .alias('/the/another/way/to/home')
+    // ... more alias path
+)
+```
+
+What if the main path included parameters? Here is how to deal with it:
+
+```ts
+$('router')
+.route('/users/:username', UserPage, route = route
+    .alias('/u/:username')
+    .alias('/profile')
+    // ^ typescript will report an error
+
+    .alias('/profile', { username: 'amateras' })
+    // ^ pass, the params required is fulfilled
+
+    .alias('/profile', () => { return { username: getUsername() } })
+    // ^ even you can pass an arrow function!
+)
+```
+
+### Group Path
+
+There have a lot of paths got same prefix? We provide the solution:
+
+```ts
+$('router')
+.route('/', HomePage)
+.group('/search', route => route
+    .route('/', SearchPage)
+    .route('/users', SearchUserPage)
+)
 ```

package/ext/router/package.json

@@ -0,0 +1,10 @@
+{
+    "name": "@amateras/router",
+    "peerDependencies": {
+        "amateras": "../../"
+    },
+    "imports": {
+      "#node/*": "./src/node/*.ts",
+      "#structure/*": "./src/structure/*.ts"
+    }
+}

package/ext/router/src/index.ts

@@ -0,0 +1,69 @@
+import type { Page } from "#node/Page";
+import { Router } from "#node/Router";
+import { PageBuilder } from "#structure/PageBuilder";
+import { Route, type RouteBuilder, type RouteParams } from "#structure/Route";
+import { _bind, _Object_assign, forEach } from "../../../src/lib/native";
+import type { AnchorTarget } from "../../html/node/$Anchor";
+
+declare module 'amateras/core' {
+    // export function $(nodeName: 'ra'): RouterAnchor;
+    export namespace $ {
+        export function route<Params extends RouteParams = []>(builder: (page: Page<Params>) => Page<Params>): PageBuilder<Params>;
+        export function open(url: string | URL | Nullish, target?: AnchorTarget): typeof Router;
+        export function replace(url: string | URL | Nullish): typeof Router;
+        export function back(): typeof Router;
+        export function forward(): typeof Router;
+        export interface $NodeMap {
+            'router': typeof Router;
+        }
+    }
+}
+
+declare global {
+    interface GlobalEventHandlersEventMap {
+        'routeopen': Event;
+    }
+}
+
+let prototype = {
+    route(this: { routes: Map<string, Route> }, path: string, builder: RouteBuilder, handle?: (route: Route) => Route) {
+        const route = new Route<any>(path, builder);
+        handle?.(route);
+        this.routes.set(path, route);
+        return this;
+    },
+
+    group(this: { routes: Map<string, Route> }, path: string, handle: (route: Route) => Route) {
+        this.routes.set(path, handle(new Route<any>(path)))
+        return this;
+    },
+
+    notFound(this: { routes: Map<string, Route> }, builder: RouteBuilder) {
+        this.routes.set('notfound', new Route('notfound', builder));
+        return this;
+    }
+}
+
+// assign methods
+_Object_assign(Router.prototype, prototype)
+_Object_assign(Route.prototype, prototype)
+_Object_assign($, {
+    route: (builder: (page: Page) => Page) => new PageBuilder(builder),
+    open: _bind(Router.open, Router),
+    replace: _bind(Router.replace, Router),
+    back: _bind(Router.back, Router),
+    forward: _bind(Router.forward, Router)
+})
+// assign node
+$.assign(['router', Router])
+// use style
+forEach([
+    `router{display:block}`,
+    `page{display:block}`
+], $.style);
+
+export * from '#node/Page';
+export * from '#node/Router';
+export * from '#node/RouterAnchor';
+export * from '#structure/PageBuilder';
+export * from '#structure/Route';

package/ext/router/src/node/Page.ts

@@ -0,0 +1,34 @@
+import type { RouteParams } from "#structure/Route";
+import { $HTMLElement } from "amateras/node/$HTMLElement";
+import { _null } from "../../../../src/lib/native";
+import type { Router } from "./Router";
+import { chain } from "../../../../src/lib/chain";
+
+export class Page<Params extends RouteParams = []> extends $HTMLElement {
+    params: PageParamsResolver<Params>;
+    router: null | Router = _null
+    #pageTitle: string | null = _null;
+    built = false;
+    constructor(params: PageParamsResolver<Params>) {
+        super('page');
+        this.params = params;
+    }
+
+    pageTitle(): string | null;
+    pageTitle(title: string | null): this;
+    pageTitle(title?: string | null) {
+        return chain(this, arguments, () => this.#pageTitle, title, title => this.#pageTitle = title)
+    }
+}
+
+export type PageParams = { [key: string]: string }
+export type PageParamsResolver<Params extends string[]> = 
+    Prettify<
+        Params extends [`${infer String}`, ...infer Rest]
+        ?   Rest extends string[]
+            ?   String extends `${infer Key}?`
+                ?   { [key in Key]?: string } & PageParamsResolver<Rest>
+                :   { [key in String]: string } & PageParamsResolver<Rest>
+            :   never
+        :   {}
+    >

package/ext/router/src/node/Router.ts

@@ -0,0 +1,191 @@
+import { $HTMLElement } from "amateras/node/$HTMLElement";
+import { Route, type RouteBuilder, type RoutePath, type RouteParamsResolver, type RouteParams, type RouteParamsStrings, type AsyncPageBuilder } from "../structure/Route";
+import { _document } from "amateras/lib/env";
+import { _instanceof, startsWith, _JSON_parse, forEach, _Object_entries, _JSON_stringify, _Object_assign, isFunction, _null } from "../../../../src/lib/native";
+import type { AnchorTarget } from "../../../html/node/$Anchor";
+import { Page, type PageParams } from "./Page";
+import type { PageBuilder, PageBuilderFunction } from "#structure/PageBuilder";
+// history index
+let index = 0;
+const _addEventListener = addEventListener;
+const _location = location;
+const {origin} = _location;
+const _history = history;
+const _sessionStorage = sessionStorage;
+const documentElement = _document.documentElement;
+const [PUSH, REPLACE] = [1, 2] as const;
+const [FORWARD, BACK] = ['forward', 'back'] as const;
+const scrollStorageKey = '__scroll__';
+/** convert path string to URL object */
+const toURL = (path: string | URL) => 
+    _instanceof(path, URL) ? path : startsWith(path, 'http') ? new URL(path) : new URL(startsWith(path, origin) ? path : origin + path);
+
+type ScrollData = {[key: number]: {x: number, y: number}};
+const scrollRecord = (e?: Event) => {
+    const data = _JSON_parse(_sessionStorage.getItem(scrollStorageKey) ?? '{}') as ScrollData;
+    data[index] = { x: documentElement.scrollLeft, y: documentElement.scrollTop };
+    // e is Event when called from scroll or beforeload
+    if (!e) forEach(_Object_entries(data), ([i]) => +i > index && delete data[+i])
+    _sessionStorage.setItem(scrollStorageKey, _JSON_stringify(data));
+}
+/** handle history state with push and replace state. */
+const historyHandler = async (path: string | URL | Nullish, mode: 1 | 2, target?: AnchorTarget) => {
+    if (!path) return;
+    const url = toURL(path);
+    if (url.href === _location.href) return;
+    if (target && target !== '_self') return open(url, target);
+    if (url.origin !== origin) return open(url, target);
+    scrollRecord();
+    if (mode === PUSH) index += 1;
+    Router.direction = FORWARD;
+    _history[mode === PUSH ? 'pushState' : 'replaceState']({index}, '' , url);
+    forEach(Router.routers, router => router.resolve(path))
+}
+// disable browser scroll restoration
+_history.scrollRestoration = 'manual';
+
+export class Router extends $HTMLElement {
+    static direction: 'back' | 'forward' = FORWARD;
+    static routers = new Set<Router>();
+    routes = new Map<RoutePath, Route>();
+    pages = new Map<string, Page>();
+    constructor(page?: Page) {
+        super('router');
+        if (page) page.router = this;
+        else Router.routers.add(this);
+    }
+    
+    static open(path: string | URL | Nullish, target?: AnchorTarget) {
+        historyHandler(path, PUSH, target);
+        return this;
+    }
+
+    static back() {
+        _history.back();
+        return this;
+    }
+
+    static forward() {
+        _history.forward();
+        return this;
+    }
+
+    static replace(path: string | URL | Nullish) {
+        historyHandler(path, REPLACE);
+        return this;
+    }
+
+    static get scroll(): ScrollData[number] {
+        return _JSON_parse(_sessionStorage.getItem(scrollStorageKey) ?? '{}')[index] ?? {x: 0, y: 0}
+    }
+    
+    listen() {
+        const resolve = () => {
+            const stateIndex = _history.state?.index ?? 0;
+            if (index > stateIndex) Router.direction = BACK;
+            if (index < stateIndex) Router.direction = FORWARD;
+            index = stateIndex;
+            this.resolve(_location.href);
+        }
+        _addEventListener('popstate', resolve);
+        _addEventListener('beforeunload', scrollRecord);
+        _addEventListener('scroll', scrollRecord, false);
+        resolve();
+        return this;
+    }
+
+    async resolve(path: string | URL): Promise<this> {
+        const {pathname, href} = toURL(path);
+        const split = (p: string) => p.replaceAll(/\/+/g, '/').replace(/^\//, '').split('/').map(path => `/${path}`);
+        type RouteData = { route: Route, params: PageParams, pathId: string }
+        const searchRoute = (routes: typeof this.routes, targetPath: string): RouteData[] => {
+            let targetPathSplit = split(targetPath);
+            if (!routes.size) return [];
+            // check each route
+            for (const [_, route] of routes) {
+                // check each path pass
+                routePathLoop: for (const [path, paramsHandle] of route.paths) {
+                    let routePathSplit = split(path);
+                    let targetPathNodePosition = 0;
+                    let params: { [key: string]: string } = isFunction(paramsHandle) ? paramsHandle() : paramsHandle ?? {};
+                    let pathId = '';
+                    // check each path node
+                    pathNodeLoop: for (let i = 0; i < routePathSplit.length; i++) {
+                        // reset target path node position
+                        targetPathNodePosition = i;
+                        const routeNode = routePathSplit[i];
+                        const targetNode = targetPathSplit[i];
+                        // path node undefined, break path loop
+                        if (!routeNode || !targetNode) continue routePathLoop;
+                        // path node is params node
+                        if (routeNode.includes(':')) {
+                            // target not matched
+                            if (targetNode === '/') continue routePathLoop;
+                            const [prefix, paramName] = routeNode.split(':') as [string, string];
+                            if (!startsWith(targetNode, prefix)) continue routePathLoop;
+                            params[paramName] = targetNode.replace(`${prefix}`, '');
+                            pathId += targetNode;
+                            continue pathNodeLoop;
+                        }
+                        // path node not matched, next path
+                        if (routeNode !== targetNode) continue routePathLoop;
+                        pathId += targetNode;
+                    }
+                    // target path node longer than route, next route
+                    if (targetPathSplit[targetPathNodePosition + 1] && !route.routes.size) continue routePathLoop;
+                    // all path node passed, route found
+                    return [{route, params, pathId}, ...searchRoute(route.routes, targetPathSplit.slice(targetPathNodePosition + 1).join('/'))]
+                }
+            }
+            // no route passed
+            const notfound = routes.get('notfound');
+            if (notfound) return [{route: notfound, params: {}, pathId: 'notfound'}]
+            return [];
+        }
+        const routes = searchRoute(this.routes, pathname);
+        let prevRouter: Router | null = this;
+        await forEach(routes, async ({route, params, pathId}) => {
+            // skip route group
+            const builderResolver = route.builder;
+            if (!builderResolver) return;
+            // get page from cache or create new page
+            const page = route.pages.get(pathId) ?? new Page(params);
+            // resolve builder
+            if (!page.built) await builderResolver.build(page);
+            page.built = true;
+            // set title
+            _document && (_document.title = page.pageTitle() ?? _document.title);
+            // check location is still same, page parent is not router before insert page
+            if (href === _location.href && page.parentNode !== prevRouter?.node) prevRouter?.content(page);
+            // set cache
+            route.pages.set(pathId, page);
+            prevRouter = page.router;
+        })
+        // handle scroll restoration
+        let { x, y } = Router.scroll ?? {x: 0, y: 0};
+        scrollTo(x, y);
+        // event
+        this.dispatchEvent(new Event('routeopen', {bubbles: true}));
+        return this;
+    }
+}
+
+export interface Router {
+    route<
+        P extends RoutePath, 
+        B extends PageBuilder
+    >(path: P, builder: B, handle?: (route: Route<P, B['params']>) => Route<P>): Router
+    route<
+        K extends RoutePath, 
+        P extends RouteParamsStrings<K>, 
+        F extends PageBuilderFunction<P>
+    >(path: K, builder: F, handle?: (route: Route<K, P>) => Route<K, P>): this
+    route<
+        K extends RoutePath, 
+        P extends RouteParamsStrings<K>, 
+        F extends AsyncPageBuilder<P>
+    >(path: K, builder: F, handle?: (route: Route<K, P>) => Route<K, P>): this
+    route<P extends RoutePath>(path: P, builder: RouteBuilder<RouteParamsResolver<P>>, handle?: (route: Route<P>) => Route<P>): Router
+    group<P extends RoutePath>(path: P, handle: <R extends Route<P>>(route: R) => R): this;
+    notFound(builder: RouteBuilder<RouteParamsResolver<RoutePath>>): this;
+}

package/ext/router/{node → src/node}/RouterAnchor.ts

@@ -1,13 +1,24 @@
-import { $Anchor } from "#html/$Anchor";
+import { $Anchor } from "../../../html/node/$Anchor";
 
 export class RouterAnchor extends $Anchor {
     constructor() {
         super();
         this.on('click', e => { 
+            if (e.shiftKey || e.ctrlKey) return;
             e.preventDefault();
             this.target() === '_replace' 
             ?   $.replace(this.href()) 
             :   $.open(this.href(), this.target())
         })
     }
-}
+}
+
+declare module 'amateras/core' {
+    export namespace $ {
+        export interface $NodeMap {
+            'ra': typeof RouterAnchor;
+        }
+    }
+}
+
+$.assign(['ra', RouterAnchor]);

package/ext/router/src/structure/PageBuilder.ts

@@ -0,0 +1,24 @@
+import { Page, type PageParams } from "#node/Page";
+import { _instanceof, _Promise, isFunction } from "../../../../src/lib/native";
+import type { $NodeContentResolver } from "../../../../src/node/$Node";
+import type { AsyncPageBuilder, RouteParams } from "./Route";
+
+export class PageBuilder<Params extends RouteParams = any> {
+    params!: Params
+    #builder: PageBuilderFunction<Params> | AsyncPageBuilder<Params>;
+    constructor(builder: PageBuilderFunction<Params>) {
+        this.#builder = builder;
+    }
+
+    async build(page: Page<Params>): Promise<Page<Params>> {
+        const resolver = this.#builder(page)
+        const handle = async (result: any) => {
+            if (_instanceof(result, Page)) return result;
+            else if (result[Symbol.toStringTag] === 'Module') return await result.default.build(page);
+            else return page.content(result);
+        }
+        return handle(_instanceof(resolver, _Promise) ? await resolver : resolver);
+    }
+}
+
+export type PageBuilderFunction<Params extends RouteParams> = (page: Page<Params>) => OrPromise<Page<Params> | $NodeContentResolver<Page<Params>>>