@vertesia/ui 0.56.0 → 0.57.0

package/src/router/HistoryNavigator.ts

@@ -0,0 +1,178 @@
+import { joinPath } from "./path";
+import { PathWithParams } from "./PathWithParams";
+
+const BASE_PATH = Symbol('BASE_PATH');
+export { BASE_PATH };
+
+export type LocationChangeEventName = 'beforeChange' | 'afterChange';
+export type LocationChangeType = 'initial' | 'popState' | 'linkClick' | 'navigate';
+export class LocationChangeEvent {
+    _canceled = false;
+    constructor(
+        public name: LocationChangeEventName,
+        public type: LocationChangeType,
+        public location: URL,
+        public state?: any) {
+    }
+
+    get isPageLoad() {
+        return this.type === 'initial';
+    }
+
+    get isBackForward() {
+        return this.type === 'popState';
+    }
+
+    get isLinkClick() {
+        return this.type === 'linkClick';
+    }
+
+    get isNavigation() {
+        return this.type === 'navigate';
+    }
+
+    get isCancelable() {
+        return this.name === 'beforeChange';
+    }
+
+    cancel() {
+        if (this.name === 'afterChange') {
+            throw new Error('Cannot cancel afterChange event');
+        }
+        this._canceled = true;
+    }
+
+}
+
+export class BeforeLocationChangeEvent extends LocationChangeEvent {
+    constructor(type: LocationChangeType, location: URL, state?: any) {
+        super('beforeChange', type, location, state);
+    }
+}
+export class AfterLocationChangeEvent extends LocationChangeEvent {
+    constructor(type: LocationChangeType, location: URL, state?: any) {
+        super('afterChange', type, location, state);
+    }
+}
+
+export interface NavigateOptions {
+    replace?: boolean;
+    state?: any;
+    /**
+     * if defined prepend the basePath to the `to` argument
+     */
+    basePath?: string;
+    /**
+     * if defined, indicate whether the basePath will be used as a top-level base path or a nested base path.
+     */
+    isBasePathNested?: boolean;
+}
+
+function getElementHrefAsUrl(elem: HTMLElement) {
+    if (elem && elem.tagName.toLowerCase() === 'a') {
+        const href = (elem as HTMLAnchorElement).href;
+        if (href != null) {
+            return new URL(href);
+        }
+    }
+    return null;
+}
+
+export class HistoryNavigator {
+    // params to preserve in the query string when navigating
+    stickyParams?: Record<string, string>;
+    _popStateListener?: (ev: PopStateEvent) => void;
+    _linkNavListener?: (ev: MouseEvent) => void;
+    _listeners: ((event: LocationChangeEvent) => void)[] = [];
+    constructor() {
+    }
+
+    addListener(listener: (event: LocationChangeEvent) => void) {
+        this._listeners.push(listener);
+    }
+
+    fireLocationChange(event: LocationChangeEvent) {
+        for (const listener of this._listeners) {
+            listener(event);
+        }
+    }
+
+    /**
+     * Should be called when the page is first loaded.
+     * It will fire a location change event with type `initial` and the current window.location as the location
+     */
+    firePageLoad() {
+        this.fireLocationChange(new AfterLocationChangeEvent('initial', new URL(window.location.href)));
+    }
+
+    addStickyParams(path: string) {
+        if (this.stickyParams) {
+            return new PathWithParams(path).add(this.stickyParams).toString();
+        }
+        return path;
+    }
+
+    navigate(to: string, options: NavigateOptions = {}) {
+        if (options.basePath) {
+            let basePath = options.basePath;
+            if (!basePath.startsWith('/')) {
+                basePath = '/' + basePath;
+            }
+            to = joinPath(basePath, to);
+        }
+        to = this.addStickyParams(to);
+        this._navigate(new URL(to, window.location.href), 'navigate', options);
+    }
+
+    _navigate(to: URL, type: LocationChangeType, options: NavigateOptions) {
+        const beforeEvent = new BeforeLocationChangeEvent(type, to, options.state);
+        this.fireLocationChange(beforeEvent);
+        if (beforeEvent._canceled) {
+            return;
+        }
+        window.history[options.replace ? 'replaceState' : 'pushState']({
+            from: window.location.href,
+            data: options.state || undefined
+        }, '', to.href);
+        this.fireLocationChange(new AfterLocationChangeEvent(type, to, options.state));
+    }
+
+    start() {
+        if (typeof window === "undefined") {
+            return;
+        }
+        const _popStateListener = (ev: PopStateEvent) => {
+            let type: LocationChangeType = ev.state ? 'popState' : 'linkClick';
+            const to = new URL(window.location.href);
+            let state: any = undefined;
+            if (ev.state) {
+                type = 'popState';
+                state = ev.state.data;
+            } else {
+                type = 'linkClick';
+            }
+            this.fireLocationChange(new AfterLocationChangeEvent(type, to, state));
+        }
+        const _linkNavListener = (ev: MouseEvent) => {
+            const url = getElementHrefAsUrl(ev.target as HTMLElement)
+            if (url && url.origin === window.location.origin) {
+                ev.preventDefault();
+                const to = new URL(this.addStickyParams(url.href));
+                const basePath = (ev as any)[BASE_PATH] || (ev.target as any)[BASE_PATH];
+                if (basePath) {
+                    to.pathname = joinPath(basePath, to.pathname);
+                }
+                this._navigate(to, 'linkClick', {});
+            }
+        }
+        this._popStateListener = _popStateListener;
+        this._linkNavListener = _linkNavListener;
+        window.addEventListener('popstate', _popStateListener);
+        document.body.addEventListener('click', this._linkNavListener);
+    }
+
+    stop() {
+        this._popStateListener && window.removeEventListener('popstate', this._popStateListener);
+        this._linkNavListener && document.body.removeEventListener('click', this._linkNavListener);
+    }
+}

package/src/router/Nav.tsx

@@ -0,0 +1,55 @@
+import { SyntheticEvent } from "react";
+import { useNavigate, useRouterContext } from "./Router";
+
+/**
+ * Wraps a <a href="..."> and perform the navigation to href through the router.
+ */
+interface NavProps {
+    children: React.ReactNode | React.ReactNode[];
+    /**
+     * A click was intercepted
+     * @param ev
+     * @returns
+     */
+    onClick?: (ev: SyntheticEvent) => void;
+}
+export function Nav({ children, onClick }: NavProps) {
+    const navigate = useNavigate();
+    const _onClick = (ev: SyntheticEvent) => {
+        const link = (ev.target as HTMLElement).closest('a');
+        if (link && link.href) {
+            ev.stopPropagation();
+            ev.preventDefault();
+            navigate(link.href);
+            onClick?.(ev);
+        }
+    }
+    return (
+        <span onClick={_onClick}>{children}</span>
+    )
+}
+
+/**
+ * A anchor tag that performs navigation through the router.
+ */
+interface NavLinkProps {
+    children: React.ReactNode | React.ReactNode[];
+    href: string;
+    className?: string;
+    /**
+     * use the root router to navigate
+     */
+    topLevelNav?: boolean;
+}
+export function NavLink({ children, href, className, topLevelNav }: NavLinkProps) {
+    const { router } = useRouterContext();
+    const _onClick = (ev: SyntheticEvent) => {
+        ev.stopPropagation();
+        ev.preventDefault();
+        const actualRouter = topLevelNav ? router.getTopRouter() : router;
+        actualRouter.navigate(href);
+    }
+    return (
+        <a href={href} className={className} onClick={_onClick}>{children}</a>
+    )
+}

package/src/router/NestedNavigationContext.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { FixLinks } from "./FixLinks";
+import { NavigateOptions } from "./HistoryNavigator";
+import { RouteComponent } from "./RouteComponent";
+import { ReactRouterContext, useRouterContext } from "./Router";
+import { joinPath } from "./path";
+
+
+interface NestedNavigationContextProps {
+    basePath: string;
+    fixLinks?: boolean;
+    children: React.ReactNode | React.ReactNode[];
+}
+export function NestedNavigationContext({ basePath, fixLinks = false, children }: NestedNavigationContextProps) {
+    const ctx = useRouterContext();
+
+    const wrapWithFixLinks = fixLinks ?
+        (elem: any) => <FixLinks basePath={ctx.matchedRoutePath}>{elem}</FixLinks>
+        : (elem: any) => elem;
+
+    return (
+        <ReactRouterContext.Provider value={{
+            ...ctx,
+            navigate: (to: string, options?: NavigateOptions) => {
+                const actualBasePath = options?.basePath ? joinPath(basePath, options.basePath) : basePath;
+                return ctx.navigate(to, { ...options, basePath: actualBasePath });
+            }
+        }}>
+            {wrapWithFixLinks(children ? children : <RouteComponent />)}
+        </ReactRouterContext.Provider>
+    )
+}

package/src/router/NestedRouterProvider.tsx

@@ -0,0 +1,64 @@
+import React, { useEffect, useMemo, useState } from "react";
+import { FixLinks } from "./FixLinks";
+import { PathMatch } from "./PathMatcher";
+import { createRoute404 } from "./Route404";
+import { RouteComponent } from "./RouteComponent";
+import { NestedRouter, ReactRouterContext, Route, useRouterContext } from "./Router";
+import { NavigateOptions } from "./HistoryNavigator";
+
+
+interface RouterProviderProps {
+    routes: Route[],
+    /**
+     * The path to use for the root resource. Defaults to '/'. Cannot contains path variables or wildcards
+     */
+    index?: string;
+    children?: React.ReactNode;
+    fixLinks?: boolean;
+}
+export function NestedRouterProvider({ routes, index, children, fixLinks = false }: RouterProviderProps) {
+    const ctx = useRouterContext();
+    const [nestedRouteMatch, setNestedRouteMatch] = useState<PathMatch<Route> | undefined>(undefined);
+    const nestedRouter = useMemo(() => {
+        if (typeof window === 'undefined') return null;
+        const basePath = ctx.matchedRoutePath;
+        const nestedRouter = new NestedRouter(ctx.router, basePath, routes);
+        nestedRouter.index = index;
+        return nestedRouter;
+    }, []);
+
+
+    useEffect(() => {
+        if (nestedRouter) {
+            if (ctx.matchedRoutePath !== nestedRouter.basePath) {
+                // the change doesn't belong to this nested router
+                // it should be handled by the top level router which will change the page or the nested router
+                return;
+            }
+            const route = nestedRouter.match(ctx.remainingPath || '/') || createRoute404();
+            setNestedRouteMatch(route);
+        }
+    }, [nestedRouter, ctx.remainingPath]);
+
+
+    const wrapWithFixLinks = fixLinks ?
+        (elem: any) => <FixLinks basePath={ctx.matchedRoutePath}>{elem}</FixLinks>
+        : (elem: any) => elem;
+
+    return nestedRouteMatch && (
+        <ReactRouterContext.Provider value={{
+            ...ctx,
+            router: nestedRouter!,
+            route: nestedRouteMatch.value,
+            params: nestedRouteMatch.params,
+            matchedRoutePath: '/' + nestedRouteMatch.matchedSegments.join('/'),
+            remainingPath: nestedRouteMatch.remainingSegments ? '/' + nestedRouteMatch.remainingSegments.join('/') : undefined,
+            navigate: (to: string, options?: NavigateOptions) => {
+                return nestedRouter!.navigate(to, options);
+            }
+
+        }}>
+            {wrapWithFixLinks(children ? children : <RouteComponent />)}
+        </ReactRouterContext.Provider>
+    )
+}

package/src/router/PathMatcher.ts

@@ -0,0 +1,166 @@
+import { PathMatchParams, getPathSegments, toSegments } from "./path";
+
+export interface PathMatch<T = any> {
+    params: PathMatchParams;
+    matchedSegments: string[];
+    remainingSegments?: string[];
+    value: T;
+}
+
+/**
+ * Path matcher which support :param and *wildcard segments.
+ * The wildcard segment is only supported as the last segment
+ */
+export class PathMatcher<T = any> {
+
+    tree: RootSegmentNode = new RootSegmentNode();
+
+    loadMapping(mapping: Record<string, T>) {
+        for (const [key, value] of Object.entries(mapping)) {
+            this.addSegments(getPathSegments(key), value);
+        }
+    }
+    addPath(path: string, value: T) {
+        this.addSegments(getPathSegments(path), value);
+    }
+    addSegments(segments: string[], value: T) {
+        let node: ParentSegmentNode<T> = this.tree;
+        for (let i = 0, l = segments.length; i < l; i++) {
+            const segment = segments[i];
+            if (segment[0] === ':') {
+                let childNode = node.wildcard;
+                if (!childNode) {
+                    childNode = new VariableSegmentNode(segment);
+                    node.wildcard = childNode;
+                } else if (!(childNode instanceof VariableSegmentNode)) {
+                    throw new Error(`Failed to index path segments: ${segments.join('/')}. A wildcard ":" segment will overwrite an existing wildcard segment at path: ${'/' + segments.slice(0, i).join("/")}`);
+                }
+                node = childNode as VariableSegmentNode;
+            } else if (segment === '*') {
+                if (node.wildcard) {
+                    throw new Error(`Failed to index path segments: ${segments.join('/')}. A wildcard "*" segment already exists at path: ${'/' + segments.slice(0, i).join("/")}`);
+                }
+                node.wildcard = new WildcardSegmentNode(segment, value);
+                if (i < l - 1) {
+                    throw new Error(`Failed to index path segments: ${segments.join('/')}. A wildcard segment must be the last segment`);
+                }
+                return;
+            } else {
+                let childNode = node.children[segment];
+                if (!childNode) {
+                    childNode = new LiteralSegmentNode(segment);
+                    node.children[segment] = childNode;
+                } // else // a literal segment already exists
+                node = childNode as LiteralSegmentNode;
+            }
+        }
+        if (node.value !== undefined) {
+            throw new Error(`Failed to index path segments: ${segments.join('/')}. A value already exists at path: ${'/' + segments.join("/")}`);
+        }
+        node.value = value;
+    }
+
+    match(path: string | string[]): PathMatch<T> | null {
+        const segments = toSegments(path);
+        if (segments.length === 0) {
+            return null;
+        }
+        const params: PathMatchParams = {};
+        let node: SegmentNode<T> = this.tree;
+        for (const segment of segments) {
+            const match = node.match(segment, params);
+            if (match) {
+                node = match;
+            } else {
+                return null;
+            }
+        }
+
+        if (!node.value) { // not a leaf node (partial match)
+            if (node instanceof ParentSegmentNode) {
+                if (node.wildcard instanceof WildcardSegmentNode) {
+                    node = node.wildcard.match('', params);
+                    if (!node.value) {
+                        throw new Error("Wildcard segment node `*` must have a value");
+                    }
+                }
+            }
+            if (!node.value) return null; // not a leaf node, neither a trailing wildcard (partial match)
+        }
+        let matchedSegments: string[], remainingSegments: string[] | undefined;
+        if (params._ && params._.length > 0) {
+            matchedSegments = segments.slice(0, -params._.length);
+            remainingSegments = params._;
+        } else {
+            matchedSegments = segments;
+        }
+        return { params, matchedSegments, remainingSegments, value: node.value };
+    }
+
+}
+
+interface SegmentNode<T = any> {
+    name: string;
+    value?: T | undefined;
+    match(segment: string, params: PathMatchParams): SegmentNode<T> | null;
+}
+class ParentSegmentNode<T = any> implements SegmentNode<T> {
+    children: Record<string, SegmentNode<T>> = {};
+    wildcard?: SegmentNode<T>;
+
+    constructor(public name: string, public value?: T | undefined) {
+    }
+
+    match(segment: string, params: PathMatchParams): SegmentNode<T> | null {
+        let node = this.children[segment];
+        if (node) {
+            return node;
+        } else if (this.wildcard) {
+            if (this.wildcard instanceof WildcardSegmentNode) {
+                return this.wildcard.match(segment, params);
+            } else if (this.wildcard instanceof VariableSegmentNode) {
+                params[this.wildcard.paramName] = segment;
+                return this.wildcard;
+            } else {
+                throw new Error("Unknown wildcard segment node type: " + this.wildcard.constructor.name);
+            }
+        } else {
+            return null;
+        }
+    }
+
+}
+
+class RootSegmentNode<T = any> extends ParentSegmentNode<T> {
+    constructor() {
+        super("#root");
+    }
+}
+
+class LiteralSegmentNode<T = any> extends ParentSegmentNode<T> {
+    constructor(name: string, value?: T | undefined) {
+        super(name, value);
+    }
+}
+
+class VariableSegmentNode<T = any> extends ParentSegmentNode<T> {
+    paramName: string;
+    constructor(name: string, value?: T | undefined) {
+        super(name, value)
+        this.paramName = name.substring(1);
+    }
+}
+
+class WildcardSegmentNode<T = any> implements SegmentNode<T> {
+    constructor(public name: string, public value?: T | undefined) {
+    }
+
+    match(segment: string, params: PathMatchParams) {
+        if (!params._) {
+            params._ = segment ? [segment] : [];
+        } else {
+            segment && params._.push(segment);
+        }
+        return this;
+    }
+}

package/src/router/PathWithParams.ts

@@ -0,0 +1,34 @@
+export class PathWithParams {
+
+    path: string;
+    params: URLSearchParams;
+    hash: string;
+
+    constructor(path: string) {
+        let i = path.lastIndexOf('#');
+        if (i > -1) {
+            this.hash = path.substring(i);
+            path = path.substring(0, i);
+        } else {
+            this.hash = '';
+        }
+        i = path.indexOf('?');
+        if (i > -1) {
+            this.path = path.substring(0, i);
+            this.params = new URLSearchParams(path.substring(i + 1));
+        } else {
+            this.path = path;
+            this.params = new URLSearchParams();
+        }
+    }
+
+    add(params: Record<string, string>) {
+        for (const [key, value] of Object.entries(params)) {
+            this.params.set(key, value);
+        }
+        return this;
+    }
+    toString() {
+        return this.path + '?' + this.params.toString() + this.hash;
+    }
+}

package/src/router/Route404.tsx

@@ -0,0 +1,18 @@
+import { RouteMatch, useRouterContext } from "./Router";
+
+export function Route404Component() {
+    const ctx = useRouterContext();
+    return <div>Route not found for path {ctx.matchedRoutePath}</div>
+}
+
+export function createRoute404(): RouteMatch {
+    return {
+        params: {},
+        matchedSegments: [],
+        state: null,
+        value: {
+            path: 'virtual:404',
+            Component: () => <Route404Component />
+        }
+    }
+}

package/src/router/RouteComponent.tsx

@@ -0,0 +1,41 @@
+import { useEffect, useState } from "react";
+import { ComponentRoute, LazyComponentRoute, useRouterContext } from "./Router";
+
+interface RouteComponentProps {
+    spinner?: React.ReactNode;
+}
+export function RouteComponent({ spinner }: RouteComponentProps) {
+    const ctx = useRouterContext();
+    const route = ctx.route;
+
+    if ((route as ComponentRoute).Component) {
+        const Component = (route as ComponentRoute).Component;
+        return <Component {...ctx.params} />
+    } else if ((route as LazyComponentRoute).LazyComponent) {
+        return <LazyRouteComponent route={route as LazyComponentRoute} spinner={spinner} />
+    } else {
+        throw new Error(`Invalid route for ${route.path}. Either Component or LazyCOmponent must be specified.`);
+    }
+}
+
+interface LazyRouteComponentProps {
+    route: LazyComponentRoute;
+    spinner?: React.ReactNode;
+}
+function LazyRouteComponent({ route, spinner }: LazyRouteComponentProps) {
+    const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+    useEffect(() => {
+        route.LazyComponent().then(module => {
+            if (!module.default) {
+                throw new Error(`Lazy module for ${route.path} does not have a default export`);
+            }
+            // we need to wrap the component type in an arrow function
+            // otherwise the setState function will execute the function as a state update function
+            setComponent(() => module.default);
+        });
+    }, [route]);
+
+    return Component ? (
+        <Component />
+    ) : spinner || null;
+}