@nutin/cli 2.1.1 → 3.0.0

package/templates/base/src/core/services/router/helpers/route-guard-manager.helper.test.js.hbs

@@ -1,4 +1,4 @@
-import { RouteGuardsManager } from '#root/dist/src/core/services/router/helpers/route-guard-manager.helper.js';
+import * as RouteGuardsManager from '#root/dist/src/core/services/router/helpers/route-guard-manager.helper.js';
 import { View } from '#root/dist/src/core/index.js';
 
 describe('RouteGuardsManager', () => {
@@ -17,40 +17,39 @@ describe('RouteGuardsManager', () => {
     expect(result).toBe(mockViewConstructor);
   });
 
-  it('should return empty guards array for function route config', () => {
-    const result = RouteGuardsManager.getRouteGuards(mockViewConstructor);
-    expect(result.length).toBe(0)
-  });
-
-  it('should return guards array from object route config', () => {
-    const guard = () => true;
-    const config = { view: mockViewConstructor, guards: [guard] };
-    const result = RouteGuardsManager.getRouteGuards(config);
-    expect(JSON.stringify(result)).toBe(JSON.stringify([guard]));
+  it('allows a function route config, which has no guards', async () => {
+    const result = await RouteGuardsManager.processRouteGuards(mockViewConstructor, '/');
+    expect(result.allowed).toBe(true);
+    expect(result.viewConstructor).toBe(mockViewConstructor);
   });
 
-  it('should default to an empty guards array when an object route config has no guards', () => {
-    const config = { view: mockViewConstructor };
-    const result = RouteGuardsManager.getRouteGuards(config);
-    expect(result).toEqual([]);
+  it('allows an object route config without guards', async () => {
+    const result = await RouteGuardsManager.processRouteGuards({ view: mockViewConstructor }, '/');
+    expect(result.allowed).toBe(true);
   });
 
-  it('should pass all guards and return true from runGuards', async () => {
-    const guards = [() => true, () => Promise.resolve(true)];
-    const result = await RouteGuardsManager.runGuards(guards);
-    expect(result).toBe(true);
+  it('runs every guard, sync or async, and allows when all return true', async () => {
+    const calls = [];
+    const guards = [() => { calls.push(1); return true; }, () => { calls.push(2); return Promise.resolve(true); }];
+    const result = await RouteGuardsManager.processRouteGuards({ view: mockViewConstructor, guards }, '/');
+    expect(result.allowed).toBe(true);
+    expect(calls).toEqual([1, 2]);
   });
 
-  it('should stop on first false from runGuards', async () => {
-    const guards = [() => true, () => false, () => true];
-    const result = await RouteGuardsManager.runGuards(guards);
-    expect(result).toBe(false);
+  it('stops at the first guard returning false', async () => {
+    let ranAfter = false;
+    const guards = [() => true, () => false, () => { ranAfter = true; return true; }];
+    const result = await RouteGuardsManager.processRouteGuards({ view: mockViewConstructor, guards }, '/');
+    expect(result.allowed).toBe(false);
+    expect(ranAfter).toBe(false);
   });
 
-  it('should stop on redirect string from runGuards', async () => {
-    const guards = [() => true, () => '/login'];
-    const result = await RouteGuardsManager.runGuards(guards);
-    expect(result).toBe('/login');
+  it('stops at the first guard returning a redirect', async () => {
+    let ranAfter = false;
+    const guards = [() => true, () => '/login', () => { ranAfter = true; return true; }];
+    const result = await RouteGuardsManager.processRouteGuards({ view: mockViewConstructor, guards }, '/');
+    expect(result.redirectTo).toBe('/login');
+    expect(ranAfter).toBe(false);
   });
 
   it('should return allowed false when guard returns false in processRouteGuards', async () => {

package/templates/base/src/core/services/router/helpers/route-guard-manager.helper.ts.hbs

@@ -1,74 +1,52 @@
-import { View } from '../../../index.js';
-
-/**
- * Route guard function that receives route parameters and returns:
- * - true to allow navigation
- * - false to block it
- * - string to redirect to a different route
- */
-export type RouteGuard = (params: Record<string, string>) => boolean | string | Promise<boolean | string>;
-
 export type GuardResult = {
   allowed: boolean,
   redirectTo?: string,
-  viewConstructor?: () => View,
+  viewConstructor?: Nutin.ViewFactory,
 }
 
-/**
- * Route configuration - can be just a view constructor or an object with guards
- */
-export type RouteConfig = (() => View) | {
-  view: () => View;
-  guards?: RouteGuard[];
-};
-
-export type Routes = Record<string, RouteConfig>;
+export function getViewConstructor(routeConfig: Nutin.RouteConfig): Nutin.ViewFactory {
+  return typeof routeConfig === 'function' ? routeConfig : routeConfig.view;
+}
 
-export class RouteGuardsManager {
-  public static getViewConstructor(routeConfig: RouteConfig): () => View {
-    return typeof routeConfig === 'function' ? routeConfig : routeConfig.view;
+export async function processRouteGuards(
+  routeConfig: Nutin.RouteConfig,
+  targetPath: string,
+  params: Record<string, string> = {}
+): Promise<GuardResult> {
+  const guards = getRouteGuards(routeConfig);
+  const guardResult = await runGuards(guards, params);
+
+  if (guardResult === false) {
+    // console.log(`Navigation to ${targetPath} blocked by route guard`);
+    return { allowed: false };
   }
 
-  public static async processRouteGuards(
-    routeConfig: RouteConfig,
-    targetPath: string,
-    params: Record<string, string> = {}
-  ): Promise<GuardResult> {
-    const guards = this.getRouteGuards(routeConfig);
-    const guardResult = await this.runGuards(guards, params);
-
-    if (guardResult === false) {
-      // console.log(`Navigation to ${targetPath} blocked by route guard`);
-      return { allowed: false };
-    }
-
-    if (typeof guardResult === 'string') {
-      // console.log(`Navigation to ${targetPath} redirected to ${guardResult} by route guard`);
-      return { allowed: false, redirectTo: guardResult };
-    }
-
-    // Guards passed
-    const viewConstructor = this.getViewConstructor(routeConfig);
-    return { allowed: true, viewConstructor };
+  if (typeof guardResult === 'string') {
+    // console.log(`Navigation to ${targetPath} redirected to ${guardResult} by route guard`);
+    return { allowed: false, redirectTo: guardResult };
   }
 
-  private static getRouteGuards(routeConfig: RouteConfig): RouteGuard[] {
-    return typeof routeConfig === 'function' ? [] : (routeConfig.guards || []);
-  }
+  // Guards passed
+  const viewConstructor = getViewConstructor(routeConfig);
+  return { allowed: true, viewConstructor };
+}
 
-  /**
-   * Runs all guards in sequence with route parameters and returns the result
-   */
-  private static async runGuards(
-    guards: RouteGuard[], 
-    params: Record<string, string>
-  ): Promise<boolean | string> {
-    for (const guard of guards) {
-      const result = await guard(params);
-      if (result !== true) {
-        return result; // false or redirect path
-      }
+function getRouteGuards(routeConfig: Nutin.RouteConfig): Nutin.RouteGuard[] {
+  return typeof routeConfig === 'function' ? [] : (routeConfig.guards || []);
+}
+
+/**
+ * Runs all guards in sequence with route parameters and returns the result
+ */
+async function runGuards(
+  guards: Nutin.RouteGuard[], 
+  params: Record<string, string>
+): Promise<boolean | string> {
+  for (const guard of guards) {
+    const result = await guard(params);
+    if (result !== true) {
+      return result; // false or redirect path
     }
-    return true;
   }
+  return true;
 }

package/templates/base/src/core/services/router/helpers/view-render-manager.helper.test.js.hbs

@@ -1,4 +1,4 @@
-import { ViewRenderManager } from '#root/dist/src/core/services/router/helpers/view-render-manager.helper.js';
+import * as ViewRenderManager from '#root/dist/src/core/services/router/helpers/view-render-manager.helper.js';
 import { AppEventBus } from '#root/dist/src/core/index.js';
 
 global.requestAnimationFrame = (cb) => setTimeout(cb, 0);
@@ -79,7 +79,7 @@ describe('ViewRenderManager', () => {
       onEnter: () => calls.push(['onEnter']),
     };
 
-    ViewRenderManager.renderNewView(() => view, { id: '42' });
+    ViewRenderManager.renderNewView(view, { id: '42' });
 
     expect(calls).toEqual([
       ['setRouteParams', { id: '42' }],
@@ -101,7 +101,7 @@ describe('ViewRenderManager', () => {
       onEnter: () => {},
     };
 
-    expect(() => ViewRenderManager.renderNewView(() => view)).not.toThrow();
+    expect(() => ViewRenderManager.renderNewView(view)).not.toThrow();
   });
 
   it('should clear stale mount content before rendering the new view', () => {
@@ -121,7 +121,7 @@ describe('ViewRenderManager', () => {
       onEnter: () => {},
     };
 
-    ViewRenderManager.renderNewView(() => view);
+    ViewRenderManager.renderNewView(view);
 
     expect(container.children.length).toBe(1);
     expect(container.contains(stale)).toBe(false);

package/templates/base/src/core/services/router/helpers/view-render-manager.helper.ts.hbs

@@ -1,41 +1,41 @@
-import { View, Lifecycle } from '../../../index.js';
+import type { View } from '../../../base-classes/view/view.js';
+import { Lifecycle } from '../../event-bus/lifecycle.facade.js';
 
 /**
  * handles all view rendering.
  */
-export class ViewRenderManager {
-  public static async transitionOutCurrentView(currentView: View | null): Promise<null> {
-    if (!currentView) return null;
-    currentView.destroy();
-    currentView.onExit();
-    Lifecycle.viewUnmount(currentView.viewName);
-    return null;
-  }
+export async function transitionOutCurrentView(currentView: View | null): Promise<null> {
+  if (!currentView) return null;
+  currentView.destroy();
+  currentView.onExit();
+  Lifecycle.viewUnmount(currentView.viewName);
+  return null;
+}
 
-  public static renderNewView(
-    viewConstructor: () => View,
-    params: Record<string, string> = {}
-  ): View {
-    const view = viewConstructor();
-    ViewRenderManager.clearStaleMountContent(view);
+// Takes the view already created by its route's factory: a lazy route's is only
+// available once its chunk has loaded.
+export function renderNewView(
+  view: View,
+  params: Record<string, string> = {}
+): View {
+  clearStaleMountContent(view);
 
-    // Set route parameters before rendering
-    view.setRouteParams(params);
+  // Set route parameters before rendering
+  view.setRouteParams(params);
 
-    view.render();
-    view.onEnter();
+  view.render();
+  view.onEnter();
 
-    Lifecycle.viewMount(view.viewName);
-    return view;
-  }
+  Lifecycle.viewMount(view.viewName);
+  return view;
+}
 
-  private static clearStaleMountContent(view: View): void {
-    const viewElement = view.getElement();
-    const container = viewElement.parentElement;
-    if (!container) return;
+function clearStaleMountContent(view: View): void {
+  const viewElement = view.getElement();
+  const container = viewElement.parentElement;
+  if (!container) return;
 
-    Array.from(container.childNodes).forEach((node) => {
-      if (node !== viewElement) node.remove();
-    });
-  }
+  Array.from(container.childNodes).forEach((node) => {
+    if (node !== viewElement) node.remove();
+  });
 }

package/templates/base/src/core/services/router/router.test.js.hbs

@@ -16,16 +16,54 @@ function makeView(name) {
   };
 }
 
+// Records pushState/replaceState URLs while still applying them to the real history.
+function trackHistory() {
+  const originalPush = window.history.pushState;
+  const originalReplace = window.history.replaceState;
+  const tracked = { pushed: [], replaced: [] };
+  window.history.pushState = function (state, title, url) {
+    tracked.pushed.push(url);
+    return originalPush.call(this, state, title, url);
+  };
+  window.history.replaceState = function (state, title, url) {
+    tracked.replaced.push(url);
+    return originalReplace.call(this, state, title, url);
+  };
+  tracked.restore = () => {
+    window.history.pushState = originalPush;
+    window.history.replaceState = originalReplace;
+  };
+  return tracked;
+}
+
+// A view whose element is in the document, with an <h1>, so it can take focus. Each gets its
+// own container: rendering a view clears its container's other children.
+function makeFocusableView(name) {
+  const view = makeView(name);
+  const el = view.getElement();
+  el.innerHTML = `<h1>${name}</h1>`;
+  const container = document.createElement('div');
+  container.appendChild(el);
+  document.body.appendChild(container);
+  view.cleanup = () => container.remove();
+  return view;
+}
+
 describe('Router', () => {
   let router = null;
 
   beforeEach(() => {
+    // Fake timers: navigating to a view without an <h1> starts the announcer's timer,
+    // which would otherwise keep the test process alive after the last test.
+    useFakeTimers();
     CONFIG.i18n = false;
     CONFIG.generateSEOFiles = false;
     window.history.pushState({}, '', '/');
   });
 
   afterEach(() => {
+    runAllTimers();
+    useRealTimers();
     if (router) {
       router.dispose();
       router = null;
@@ -88,6 +126,52 @@ describe('Router', () => {
     expect(router.getParam('id')).toBe('42');
   });
 
+  it('navigate() keeps the query string and decodes route params', async () => {
+    const home = makeView('home');
+    const userView = makeView('user');
+    router = AppRouter({ '/': () => home, '/users/:name': () => userView });
+    await flushPromises();
+
+    await router.navigate('/users/J%C3%B6rg?tab=posts#top');
+
+    expect(router.getParam('name')).toBe('Jörg');
+    expect(window.location.pathname + window.location.search + window.location.hash).toBe('/users/J%C3%B6rg?tab=posts#top');
+  });
+
+  it('reload() keeps the current query string', async () => {
+    const home = makeView('home');
+    const list = makeView('list');
+    router = AppRouter({ '/': () => home, '/list': () => list });
+    await flushPromises();
+    await router.navigate('/list?page=2');
+
+    await router.reload();
+
+    expect(window.location.search).toBe('?page=2');
+  });
+
+  it('drops a navigation whose guard resolves after a newer navigation started', async () => {
+    const home = makeView('home');
+    const slow = makeView('slow');
+    const fast = makeView('fast');
+    let releaseGuard;
+    router = AppRouter({
+      '/': () => home,
+      '/slow': { view: () => slow, guards: [() => new Promise((resolve) => { releaseGuard = resolve; })] },
+      '/fast': () => fast,
+    });
+    await flushPromises();
+
+    const slowNav = router.navigate('/slow');
+    await router.navigate('/fast');
+    releaseGuard(true);
+    await slowNav;
+
+    expect(slow.calls.length).toBe(0);
+    expect(fast.calls.some(c => c[0] === 'render')).toBe(true);
+    expect(window.location.pathname).toBe('/fast');
+  });
+
   it('navigate() renders the /404 route when no pattern matches', async () => {
     const home = makeView('home');
     const notFound = makeView('not-found');
@@ -144,6 +228,91 @@ describe('Router', () => {
     expect(secret.calls.length).toBe(0);
   });
 
+  it('navigate() pushes the redirect target when an in-app navigation is redirected by a guard', async () => {
+    const home = makeView('home');
+    const login = makeView('login');
+    const secret = makeView('secret');
+    router = AppRouter({
+      '/': () => home,
+      '/login': () => login,
+      '/secret': { view: () => secret, guards: [() => '/login'] },
+    });
+    await flushPromises();
+    const history = trackHistory();
+
+    await router.navigate('/secret');
+    history.restore();
+
+    expect(history.pushed).toEqual(['/login']);
+    expect(history.replaced).toEqual([]);
+    expect(window.location.pathname).toBe('/login');
+  });
+
+  it('replaces the guarded URL with the redirect target on first load', async () => {
+    const login = makeView('login');
+    const secret = makeView('secret');
+    window.history.pushState({}, '', '/secret');
+    const history = trackHistory();
+
+    router = AppRouter({
+      '/login': () => login,
+      '/secret': { view: () => secret, guards: [() => '/login'] },
+    });
+    await flushPromises();
+    history.restore();
+
+    expect(login.calls.some(c => c[0] === 'render')).toBe(true);
+    expect(history.pushed).toEqual([]);
+    expect(history.replaced).toEqual(['/login']);
+    expect(window.location.pathname).toBe('/login');
+  });
+
+  it('replaces the guarded URL with the redirect target on popstate', async () => {
+    const home = makeView('home');
+    const login = makeView('login');
+    const secret = makeView('secret');
+    router = AppRouter({
+      '/': () => home,
+      '/login': () => login,
+      '/secret': { view: () => secret, guards: [() => '/login'] },
+    });
+    await flushPromises();
+
+    window.history.pushState({}, '', '/secret');
+    const history = trackHistory();
+    window.dispatchEvent(new window.PopStateEvent('popstate'));
+    await flushPromises();
+    history.restore();
+
+    expect(login.calls.some(c => c[0] === 'render')).toBe(true);
+    expect(secret.calls.length).toBe(0);
+    expect(history.pushed).toEqual([]);
+    expect(history.replaced).toEqual(['/login']);
+    expect(window.location.pathname).toBe('/login');
+  });
+
+  it('reload() replaces the current URL when its guard now redirects', async () => {
+    let loggedIn = true;
+    const login = makeView('login');
+    const account = makeView('account');
+    window.history.pushState({}, '', '/account');
+    router = AppRouter({
+      '/login': () => login,
+      '/account': { view: () => account, guards: [() => loggedIn || '/login'] },
+    });
+    await flushPromises();
+
+    loggedIn = false;
+    const history = trackHistory();
+    await router.reload();
+    history.restore();
+
+    expect(login.calls.some(c => c[0] === 'render')).toBe(true);
+    expect(history.pushed).toEqual([]);
+    expect(history.replaced).toEqual(['/login']);
+    expect(window.location.pathname).toBe('/login');
+  });
+
   it('navigate() renders the view when all guards pass', async () => {
     const home = makeView('home');
     const dashboard = makeView('dashboard');
@@ -321,4 +490,141 @@ describe('Router', () => {
     await flushPromises();
     expect(about.calls.length).toBe(0);
   });
+
+  it('leaves focus alone on the first load', async () => {
+    const home = makeFocusableView('home');
+    router = AppRouter({ '/': () => home });
+    await flushPromises();
+    expect(document.activeElement).not.toBe(home.getElement().querySelector('h1'));
+    home.cleanup();
+  });
+
+  it('focuses the new view\'s h1 on navigate()', async () => {
+    const home = makeFocusableView('home');
+    const about = makeFocusableView('about');
+    router = AppRouter({ '/': () => home, '/about': () => about });
+    await flushPromises();
+
+    await router.navigate('/about');
+    expect(document.activeElement).toBe(about.getElement().querySelector('h1'));
+    home.cleanup();
+    about.cleanup();
+  });
+
+  it('focuses the view on back/forward (popstate)', async () => {
+    const home = makeFocusableView('home');
+    const about = makeFocusableView('about');
+    router = AppRouter({ '/': () => home, '/about': () => about });
+    await flushPromises();
+
+    window.history.pushState({}, '', '/about');
+    window.dispatchEvent(new window.PopStateEvent('popstate'));
+    await flushPromises();
+    expect(document.activeElement).toBe(about.getElement().querySelector('h1'));
+    home.cleanup();
+    about.cleanup();
+  });
+
+  it('focuses the /404 view on an in-app navigation to an unknown path', async () => {
+    const home = makeFocusableView('home');
+    const notFound = makeFocusableView('not-found');
+    router = AppRouter({ '/': () => home, '/404': () => notFound });
+    await flushPromises();
+
+    await router.navigate('/nowhere');
+    expect(document.activeElement).toBe(notFound.getElement().querySelector('h1'));
+    home.cleanup();
+    notFound.cleanup();
+  });
+
+  it('does not move focus on reload()', async () => {
+    const home = makeFocusableView('home');
+    router = AppRouter({ '/': () => home });
+    await flushPromises();
+    const outside = document.createElement('button');
+    document.body.appendChild(outside);
+    outside.focus();
+
+    await router.reload();
+    expect(document.activeElement).toBe(outside);
+    outside.remove();
+    home.cleanup();
+  });
+
+  it('renders a lazy route once its factory resolves, keeping the current view up meanwhile', async () => {
+    const home = makeView('home');
+    const about = makeView('about');
+    let resolveAbout;
+    router = AppRouter({ '/': () => home, '/about': () => new Promise((resolve) => { resolveAbout = resolve; }) });
+    await flushPromises();
+
+    const navigation = router.navigate('/about');
+    await flushPromises();
+    expect(home.calls.some((c) => c[0] === 'destroy')).toBe(false);
+    expect(window.location.pathname).toBe('/');
+
+    resolveAbout(about);
+    await navigation;
+    expect(home.calls.some((c) => c[0] === 'destroy')).toBe(true);
+    expect(about.calls.map((c) => c[0])).toEqual(['setRouteParams', 'render', 'onEnter']);
+    expect(window.location.pathname).toBe('/about');
+  });
+
+  it('renders a lazy /404 route', async () => {
+    const home = makeView('home');
+    const notFound = makeView('not-found');
+    router = AppRouter({ '/': () => home, '/404': () => Promise.resolve(notFound) });
+    await flushPromises();
+
+    await router.navigate('/nowhere');
+    expect(notFound.calls.some((c) => c[0] === 'render')).toBe(true);
+  });
+
+  it('drops a lazy view that resolves after a newer navigation started', async () => {
+    const home = makeView('home');
+    const slow = makeView('slow');
+    const fast = makeView('fast');
+    let resolveSlow;
+    router = AppRouter({
+      '/': () => home,
+      '/slow': () => new Promise((resolve) => { resolveSlow = resolve; }),
+      '/fast': () => fast,
+    });
+    await flushPromises();
+
+    const slowNavigation = router.navigate('/slow');
+    await flushPromises();
+    await router.navigate('/fast');
+    resolveSlow(slow);
+    await slowNavigation;
+
+    expect(slow.calls.map((c) => c[0])).toEqual(['destroy']);
+    expect(fast.calls.some((c) => c[0] === 'render')).toBe(true);
+    expect(window.location.pathname).toBe('/fast');
+  });
+
+  it('falls back to a full page load of the target URL when a lazy view fails to load', async () => {
+    // The full page load itself (location.assign) is a no-op in jsdom: the record written
+    // right before it, in sessionStorage, shows it was attempted, and for which URL.
+    sessionStorage.clear();
+    const home = makeView('home');
+    const record = () => JSON.parse(sessionStorage.getItem('nutin:failed-view-load') ?? 'null');
+    try {
+      router = AppRouter({ '/': () => home, '/docs': () => Promise.reject(new TypeError('Failed to fetch dynamically imported module')) });
+      await flushPromises();
+
+      await silenceConsole('error', async () => {
+        await router.navigate('/docs?page=2#intro');
+        expect(record().url).toBe('/docs?page=2#intro');
+        expect(home.calls.some((c) => c[0] === 'destroy')).toBe(false);
+
+        // Failing again right after the reload: logged only, no reload loop (the record is kept as is).
+        const first = record().at;
+        await router.navigate('/docs?page=2#intro');
+        expect(record().at).toBe(first);
+      });
+    } finally {
+      sessionStorage.clear();
+    }
+  });
 });