@lwrjs/router 0.10.0-alpha.1 → 0.10.0-alpha.10

package/build/es/modules/lwr/historyRouter/historyRouter.js

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2019, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { DomRouterImpl } from 'lwr/domRouter';
+import { getRelativeUrl, replace, set } from 'lwr/domRouterUtils';
+import { hasDocument } from 'lwr/routerUtils';
+/*
+ * Provides a Router rooted to the window, which controls the browser history by default.
+ */
+export class HistoryRouter extends DomRouterImpl {
+    constructor() {
+        super(...arguments);
+        this.historyDisabled = false;
+    }
+    /**
+     * Override.
+     * Initialize with the current route and listen to the popstate event for future changes.
+     */
+    connect() {
+        super.connect();
+        if (!this.historyDisabled) {
+            // Subscribe to the Window.popstate event to listen for URL changes.
+            hasDocument && window.addEventListener('popstate', this.onpopstate.bind(this));
+            // Initialize using the current URL state
+            this.onpopstate();
+        }
+    }
+    onpopstate() {
+        // Only the root should update the url since it has the full context
+        if (!this.parent && hasDocument) {
+            this.catchBrowserUpdate(getRelativeUrl(document.location.href));
+        }
+    }
+    disconnect() {
+        super.disconnect();
+        hasDocument && window.removeEventListener('popstate', this.onpopstate);
+    }
+    /**
+     * Override.
+     * Update the browser history if the preNavigate hooks.
+     *
+     * @param {string} url - The URL to go to
+     * @param {boolean} shouldReplace - True if the current history state should be replaced
+     * @param {boolean} updateHistory - True if the browser history should be updated with the new URL
+     *
+     * @returns {boolean} - True if the processing was NOT blocked by a preNavigate listener
+     */
+    async process(url, shouldReplace, updateHistory = true) {
+        // Run the preNavigate hooks to check if this event should be processed.
+        const canContinue = await super.process(url);
+        // Update the window location if this router is connected and is the root router
+        if (canContinue && !this.historyDisabled && updateHistory && this.connected && !this.parent) {
+            // Update the window history.
+            if (shouldReplace) {
+                replace(url);
+            }
+            else {
+                set(url);
+            }
+        }
+        return canContinue;
+    }
+    /**
+     * Update the root route, and trickle down the router tree.
+     * Redirect to use the base path, if it is missing.
+     *
+     * @param {string} url - The URL to go to
+     */
+    catchBrowserUpdate(url) {
+        this.process(url, false, false);
+    }
+}
+/**
+ * Create a new root Router, attach to the Window.
+ * This is the public, programmitic API for root router creation.
+ * An application can only have ONE root router.
+ *
+ * @param {object} config - The router config object
+ *
+ * @returns {object} - { addPreNavigate, addPostNavigate, addErrorNavigate, connect, disconnect }
+ */
+export function createHistoryRouter(config, router, target) {
+    return new HistoryRouter(config, router, target);
+}
+//# sourceMappingURL=historyRouter.js.map

package/build/es/modules/lwr/navigation/navigation.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2019, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+// Wires and their return types
+export { NavigationContext } from 'lwr/navigationContext'; // provides ContextId
+export { CurrentPageReference } from 'lwr/currentPageReference'; // provides PageReference
+export { CurrentView } from 'lwr/currentView'; // Provides Constructable
+// The LWR Navigation context singleton (i.e. CACHE in lwr/contextUtils#navigationApiStore)
+// These functions and classes must only be included in an app ONCE:
+//      - 'lwr/navigation' must be excluded from bundling
+//      - ALWAYS import these from 'lwr/navigation', even internally
+export { ContextInfo, getNavigationHelm, registerNavigationHelm, generateContextualWireAdapter, } from 'lwr/contextUtils';
+// NavigationMixin has a dependency on navigate and generateUrl
+// They need to be sibling exports in order to avoid a circular dependency
+export { navigate, generateUrl } from './navigationApi';
+export { NavigationMixin } from './navigationMixin';
+//# sourceMappingURL=navigation.js.map

package/build/es/modules/lwr/navigation/navigationApi.js

@@ -0,0 +1,27 @@
+import { getNavigationHelm } from 'lwr/contextUtils';
+/**
+ * Navigate programmatically.
+ * The Promise used within is deliberately not returned.
+ *
+ * @param {HTMLElement} context - The navigation context
+ * @param {object | string} loc - A route or URL for navigating
+ * @param {*} options - Usually a boolean; when true the previous browser history
+ *              entry should be replaced by this one
+ */
+export function navigate(context, pageReference, replace) {
+    const api = getNavigationHelm(context);
+    api.navigate(pageReference, replace);
+}
+/**
+ * Generate a URL for the given route.
+ *
+ * @param {HTMLElement} context - The navigation context
+ * @param {object} route - A route
+ *
+ * @returns {Promise<string>}
+ */
+export function generateUrl(context, pageReference) {
+    const api = getNavigationHelm(context);
+    return api.generateUrl(pageReference);
+}
+//# sourceMappingURL=navigationApi.js.map

package/build/es/modules/lwr/navigation/navigationMixin.js

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2019, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+// TODO: The way NavigationMixin is currently set up, we need to use unique
+// symbols as indexes, which typescript does not like, necessitating 'any'
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { invariant, generateMessage, messages } from 'lwr/routerErrors';
+import { generateUrl, navigate } from './navigationApi';
+import { CONTEXT_ID_BACKDOOR } from 'lwr/navigationMixinHacks';
+/*
+ * Exports the NavigationMixin and CurrentPageReference wire adapter.
+ * Uses the NavigationContext wire to retrieve the current navigation context/node.
+ */
+/**
+ * Provides navigate() and generateUrl() functionality.
+ * Here, navigate() can take either a route OR a string URL.
+ * Functionality pulled in from the current navigation context.
+ * Used by components as a Mixin to extend their own functionality.
+ *
+ * @param {HTMLElement} Base - A class instance
+ */
+const Navigate = Symbol('Navigate');
+const GenerateUrl = Symbol('GenerateUrl');
+const NavContext = Symbol('NavContext');
+const GetContext = Symbol('NavContext');
+function NavigationMixin(Base) {
+    invariant(typeof Base.prototype.dispatchEvent === 'function', messages.INVALID_MIXIN_CMP, [
+        Base.toString(),
+    ]);
+    class Mixin extends Base {
+        [GetContext]() {
+            /*
+             * NavigationMixin is a special snowflake that needs to use the DOM to lookup its parent ContextId,
+             * but is not allowed to use the traditional means: @wire(NavigationContext) to do so, because it's
+             * part of the navigation API, which must be importable into the priming environment, and thus cannot
+             * import anything from LWC. Best solution we have so far is a CustomEvent that allows the module to
+             * be imported, but cannot be RAN in the priming environment. This is acceptable because it's generally
+             * a component that extends LightningElement that's using the NavigationMixin, rather than any priming code.
+             */
+            if (!this[NavContext]) {
+                this.dispatchEvent(
+                // eslint exception reason: this code is safe to be imported into the priming environment, but is not runnable, and not expected to be runnable
+                // eslint-disable-next-line no-undef
+                new CustomEvent(CONTEXT_ID_BACKDOOR, {
+                    bubbles: true,
+                    composed: true,
+                    detail: {
+                        callback: (contextId) => {
+                            this[NavContext] = contextId;
+                        },
+                    },
+                }));
+                if (!this[NavContext]) {
+                    throw new Error(generateMessage(messages.MISSING_CONTEXT));
+                }
+            }
+        }
+        [Navigate](pageRef, replace) {
+            this[GetContext]();
+            navigate(this[NavContext], pageRef, replace);
+        }
+        async [GenerateUrl](pageRef) {
+            this[GetContext]();
+            return generateUrl(this[NavContext], pageRef);
+        }
+    }
+    return Mixin;
+}
+NavigationMixin.Navigate = Navigate;
+NavigationMixin.GenerateUrl = GenerateUrl;
+NavigationMixin.NavContext = NavContext;
+export { NavigationMixin };
+//# sourceMappingURL=navigationMixin.js.map

package/build/{modules → es/modules}/lwr/navigationContext/navigationContext.d.ts

@@ -1,5 +1,5 @@
-export declare type ContextId = () => void;
-declare type NavigationContextType = ContextId | undefined;
+export type ContextId = () => void;
+type NavigationContextType = ContextId | undefined;
 export declare const NavigationContext: import("lwr/contextUtils").ContextualWireAdapter<NavigationContextType, unknown, NavigationContextType>;
 export {};
 //# sourceMappingURL=navigationContext.d.ts.map

package/build/es/modules/lwr/navigationContext/navigationContext.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2019, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { ContextInfo, generateContextualWireAdapter } from 'lwr/contextUtils';
+const NAVIGATION_CONTEXT = new ContextInfo(undefined);
+export const NavigationContext = generateContextualWireAdapter(NAVIGATION_CONTEXT);
+//# sourceMappingURL=navigationContext.js.map

package/build/es/modules/lwr/navigationMixinHacks/navigationMixinHacks.d.ts

@@ -0,0 +1,7 @@
+export declare const CONTEXT_ID_BACKDOOR: string;
+export type NavigationContextBackdoorEvent = globalThis.CustomEvent<NavigationContextBackdoorEventPayload>;
+import type { ContextId } from 'lwr/navigation';
+export type NavigationContextBackdoorEventPayload = {
+    callback: (contextId: ContextId) => void;
+};
+//# sourceMappingURL=navigationMixinHacks.d.ts.map

package/build/es/modules/lwr/navigationMixinHacks/navigationMixinHacks.js

@@ -0,0 +1,5 @@
+// This is claimed to be a portable module, but it really isn't. It can be imported, but will not RUN in the portable environment
+import { guid } from 'lwr/routerUtils';
+// A hack to get NavigationMixin working without requiring lwc
+export const CONTEXT_ID_BACKDOOR = `universalcontainergetnavigationcontext${guid()}`;
+//# sourceMappingURL=navigationMixinHacks.js.map

package/build/es/modules/lwr/observable/observable.js

@@ -0,0 +1,71 @@
+/**
+ * Creates a simple observable object, which can have any number of observers.
+ * @returns {object}
+ */
+export function createObservable() {
+    // Keep track of the current value and error.
+    let currentValue = undefined;
+    let currentError = undefined;
+    // Observer list with functions to add and remove members safely.
+    let observers = [];
+    const addObserver = (obs) => {
+        observers.push(obs);
+    };
+    const removeObserver = (obsIndex) => {
+        // copy on delete prevents issues when an observer unsubscribes while iterating over them
+        observers = [...observers.slice(0, obsIndex), ...observers.slice(obsIndex + 1)];
+    };
+    // On next, broadcast the value to all observers.
+    // Clear out current error.
+    const next = (value) => {
+        observers
+            .filter((obs) => obs !== null)
+            .forEach((obs) => obs.next && obs.next(value));
+        currentValue = value;
+        currentError = undefined;
+    };
+    // On error, broadcast the error to all observers.
+    // Clear out current value.
+    const error = (err) => {
+        observers
+            .filter((obs) => obs !== null)
+            .forEach((obs) => obs.error && obs.error(err));
+        currentValue = undefined;
+        currentError = err;
+    };
+    // On complete, call complete on all observers.
+    // Clear out all observers + current value and error.
+    const complete = () => {
+        observers
+            .filter((obs) => obs !== null)
+            .forEach((obs) => obs.complete && obs.complete());
+        observers = [];
+        currentValue = undefined;
+        currentError = undefined;
+    };
+    // Observable can be subscribed and unsubscribed, by multiple observers.
+    // When replay is true, the currentValue will be emitted synchronously.
+    const subscribe = (obs, replay = true) => {
+        addObserver(obs);
+        // Push the current value and error, if they exist.
+        if (currentValue && replay) {
+            obs.next(currentValue);
+        }
+        if (currentError) {
+            error(currentError);
+        }
+        // On unsubscribe, the observer is nulled out.
+        const obsIndex = observers.length - 1;
+        return {
+            unsubscribe: () => removeObserver(obsIndex),
+        };
+    };
+    // Return the observation methods + the associated observable.
+    return {
+        next,
+        error,
+        complete,
+        subscribe,
+    };
+}
+//# sourceMappingURL=observable.js.map

package/build/{modules → es/modules}/lwr/outlet/outlet.d.ts

@@ -4,6 +4,7 @@ export interface OutletErrorCallback {
     (error: Error, stack: string): void;
 }
 export default class Outlet extends LightningElement {
+    static renderMode: string;
     refocusOff: boolean;
     outletErrorCallback?: OutletErrorCallback;
     viewName: string;

package/build/es/modules/lwr/outlet/outlet.js

@@ -0,0 +1,69 @@
+var __decorate = (this && this.__decorate) || function (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;
+};
+import { LightningElement, api, wire } from 'lwc';
+import { CurrentView } from 'lwr/navigation';
+export default class Outlet extends LightningElement {
+    constructor() {
+        super(...arguments);
+        this.refocusOff = false;
+        this.viewName = 'default';
+        this.viewCtor = undefined;
+        this.previousViewCtor = undefined;
+        this.hasError = false;
+    }
+    // Get a reference to the current view
+    setView(currentView) {
+        this.hasError = false;
+        this.viewCtor = currentView;
+        this.refocus();
+    }
+    renderedCallback() {
+        if (this.viewCtor !== this.previousViewCtor) {
+            this.previousViewCtor = this.viewCtor;
+            const viewChangedEvent = new CustomEvent('viewchange', { detail: this.viewCtor });
+            this.dispatchEvent(viewChangedEvent);
+        }
+    }
+    errorCallback(e, stack) {
+        // when hosted view has unhandled error thrown:
+        //  - display the error slot
+        //  - dispatch the "viewchange" event
+        //  - call the outletErrorCallback()
+        this.hasError = true;
+        const viewErrorEvent = new CustomEvent('viewerror', { detail: { error: e, stack } });
+        this.dispatchEvent(viewErrorEvent);
+        if (this.outletErrorCallback) {
+            this.outletErrorCallback(e, stack);
+        }
+        else {
+            console.error(e);
+        }
+    }
+    refocus() {
+        // If the feature is not turned off, put the browser focus onto the dynamic content.
+        // This is done after a route change for accessibility.
+        if (!this.refocusOff) {
+            const region = this.querySelector(`div[role='region'].outlet`);
+            if (region)
+                region.focus();
+        }
+    }
+}
+Outlet.renderMode = 'light';
+__decorate([
+    api
+], Outlet.prototype, "refocusOff", void 0);
+__decorate([
+    api
+], Outlet.prototype, "outletErrorCallback", void 0);
+__decorate([
+    api
+], Outlet.prototype, "viewName", void 0);
+__decorate([
+    wire(CurrentView, { viewName: '$viewName' })
+], Outlet.prototype, "setView", null);
+//# sourceMappingURL=outlet.js.map

package/build/es/modules/lwr/router/router.js

@@ -0,0 +1,201 @@
+/**
+ * Copyright (c) 2019, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { freeze, getUrlFromPageReference, getPageReferenceFromUrl, matchRouteByUrl, getUrlFromPageReferenceAndRouteDef, parseRoutes, } from 'lwr/routerUtils';
+import { generateMessage, messages } from 'lwr/routerErrors';
+import { createObservable } from 'lwr/observable';
+class RouterImpl {
+    /**
+     * Create and configure the Router.
+     *
+     * @param {object} config - The router config object, all properties are optional
+     */
+    constructor(config) {
+        this.deprecatedConfig = {};
+        this.routeHandlerId = 0;
+        this.compiledRoutes = [];
+        this.routeObservable = createObservable();
+        this.config = {
+            basePath: config.basePath || '',
+            caseSensitive: Boolean(config.caseSensitive),
+            routes: config.routes || [],
+            generateUrl: (address) => getUrlFromPageReference(address, this.compiledRoutes, this.config.basePath),
+            parseUrl: (url) => getPageReferenceFromUrl(url, this.compiledRoutes, this.config.basePath),
+        };
+        const { DEPRECATED_getRouteFromUrl, DEPRECATED_getUrlFromRoute } = config;
+        if (DEPRECATED_getRouteFromUrl) {
+            this.deprecatedConfig.DEPRECATED_getRouteFromUrl = DEPRECATED_getRouteFromUrl;
+        }
+        if (DEPRECATED_getUrlFromRoute) {
+            this.deprecatedConfig.DEPRECATED_getUrlFromRoute = DEPRECATED_getUrlFromRoute;
+        }
+        this.compiledRoutes = parseRoutes(this.config);
+    }
+    /**
+     * Convert address to url string.
+     *
+     * @param address
+     */
+    generateUrl(address) {
+        const { DEPRECATED_getUrlFromRoute: getUrlFromRoute } = this.deprecatedConfig;
+        if (getUrlFromRoute) {
+            return getUrlFromRoute(address, this.config.generateUrl);
+        }
+        else {
+            return this.config.generateUrl(address);
+        }
+    }
+    /**
+     * Convert url string to address.
+     *
+     * @param url
+     */
+    parseUrl(url) {
+        const { DEPRECATED_getRouteFromUrl: getRouteFromUrl } = this.deprecatedConfig;
+        if (getRouteFromUrl) {
+            return getRouteFromUrl(url, this.config.parseUrl);
+        }
+        else {
+            return this.config.parseUrl(url);
+        }
+    }
+    /**
+     * Match the given url against the internal route definitions and return info
+     * on the match.
+     *
+     * @param address - The address to match
+     */
+    matchRoute(address) {
+        const url = typeof address === 'string' ? address : this.generateUrl(address);
+        if (url === null) {
+            return null;
+        }
+        const match = matchRouteByUrl(url, this.compiledRoutes, this.config.basePath);
+        const pathMatch = match &&
+            getUrlFromPageReferenceAndRouteDef(match.route.pageReference, match.routeDefinition, this.config.basePath);
+        if (!match || !pathMatch) {
+            return null;
+        }
+        return {
+            pathMatch,
+            route: match.route,
+            routeDefinition: match.routeDefinition.original,
+        };
+    }
+    /**
+     * Given an address, return the associated viewset by calling the route handler.
+     *
+     * @param address - The address to match to a viewset
+     */
+    async resolveView(address) {
+        return new Promise((resolve, reject) => {
+            // get the RoutingMatch: { pathMatch, route, routeDefinition }
+            const routingMatch = this.matchRoute(address);
+            if (!routingMatch) {
+                return reject(generateMessage(messages.NO_ROUTE_MATCH, [JSON.stringify(address)]));
+            }
+            // retrieve the route handler and use it to get the RouteDestination
+            // handler ~= import('my/handlerModule');
+            return routingMatch.routeDefinition.handler().then((handlerModule) => {
+                // the route handler class is the module's default export
+                const routeHandlerClass = handlerModule.default;
+                if (!routeHandlerClass) {
+                    return reject(generateMessage(messages.INVALID_ROUTE_HANDLER, [routingMatch.routeDefinition.id]));
+                }
+                // instantiate an instance of the route handler class
+                // and pass in resolve() as the RouteHandlerCallback
+                const routeHandler = new routeHandlerClass(resolve);
+                // update() will invoke the resolve callback with the matching RouteDestination/viewset
+                if (routeHandler) {
+                    routeHandler.update(routingMatch.route);
+                }
+            });
+        });
+    }
+    /**
+     * Process the given URL by matching it to an existing route and looking up
+     * the associated view
+     *
+     * @param {object} address
+     */
+    navigate(address) {
+        const routingMatch = this.matchRoute(address);
+        if (!routingMatch) {
+            throw new Error(generateMessage(messages.MISSING_ROUTE, [JSON.stringify(address)]));
+        }
+        this.pendingRoute = { ...routingMatch };
+        // map the matched route to a view and notify subscribers
+        this._mapView(this.pendingRoute);
+    }
+    /**
+     * lightning/navigation
+     * Subscribe a callback to the Observable on the current route of this router.
+     *
+     * @param {function} callback - A callback function invoked when the navigation state changes
+     *                     callback(route, routeDef)
+     * @param {boolean} replay - Flag to determine if callback should be called with current route and data immediately
+     */
+    subscribe(callback, replay) {
+        return this.routeObservable.subscribe({
+            next: callback,
+            error: () => {
+                // ignore
+            },
+            complete: () => {
+                // nothing to clean up
+            },
+        }, Boolean(replay));
+    }
+    /**
+     * Map the given route to a view set that can be emitted to subscribers. After the correct handler
+     * is determined (picked from the routers routes in the config), view mapping is delegated to the
+     * handler with a callback to finish processing and emit the final result.
+     *
+     * @param {*} route
+     * @param {*} routeInfo
+     */
+    async _mapView(routingMatch) {
+        // set an id in case _mapView is called again.
+        const routeHandlerId = Math.random();
+        this.routeHandlerId = routeHandlerId;
+        const handlerModule = await routingMatch.routeDefinition.handler();
+        const routeHandlerClass = handlerModule.default;
+        if (!routeHandlerClass) {
+            throw new Error(generateMessage(messages.INVALID_ROUTE_HANDLER, [routingMatch.routeDefinition.id]));
+        }
+        this.routeHandler = new routeHandlerClass((routeDestination) => {
+            // If the id in the callback no longer matches the latest id from the router, it indicates _mapView
+            // was called again after this handler began loading but before the callback completed.
+            this._updateView(routeHandlerId, routeDestination);
+        });
+        if (this.routeHandler) {
+            this.routeHandler.update(routingMatch.route);
+        }
+        return true;
+    }
+    /**
+     * Set internal state, notify observable with frozen data, and propagate to child router
+     *
+     * @param {*} viewDestination
+     */
+    _updateView(viewHandlerId, routeDestination) {
+        if (!routeDestination || viewHandlerId !== this.routeHandlerId) {
+            // no-op, a status handler stopped the action
+            // or this callback does not belong to the most recent view handler.
+            return;
+        }
+        if (!this.pendingRoute) {
+            throw new Error('Trying to commit route state without a route');
+        }
+        const viewset = freeze(routeDestination.viewset);
+        this.routeObservable.next({ ...this.pendingRoute, ...routeDestination, viewset });
+    }
+}
+// export the function only instead of the class, may give us more flexibility in the future
+export function createRouter(config = {}) {
+    return new RouterImpl(config);
+}
+//# sourceMappingURL=router.js.map