@nutin/cli 2.1.0 → 3.0.0

package/templates/base/src/core/services/router/router.ts.hbs

@@ -1,22 +1,17 @@
-import { View, Navigation, Service, I18nService, AppEventBus } from '../../index.js';
-import { Language } from '../i18n/languages.js';
-import { Routes, RouteConfig, RouteGuardsManager, GuardResult } from './helpers/route-guard-manager.helper.js';
-import { ViewRenderManager } from './helpers/view-render-manager.helper.js';
-import { NavigationManager } from './helpers/navigation-manager.helper.js';
+import type { View } from '../../base-classes/view/view.js';
+import { Service } from '../../base-classes/service/service.js';
+import { Navigation } from '../event-bus/navigation.facade.js';
+import { AppEventBus } from '../event-bus/event-bus.js';
+import { I18nService } from '../i18n/i18n.js';
+import * as RouteGuardsManager from './helpers/route-guard-manager.helper.js';
+import type { GuardResult } from './helpers/route-guard-manager.helper.js';
+import * as ViewRenderManager from './helpers/view-render-manager.helper.js';
+import * as NavigationManager from './helpers/navigation-manager.helper.js';
+import type { HistoryMode } from './helpers/navigation-manager.helper.js';
+import { CONFIG } from '../../config.js';
 
 // centralized export
-export { Routes, RouteGuard } from './helpers/route-guard-manager.helper.js';
-
-/**
- * IRouter is a type alias for the instance of Router, not a true interface 
- */
-export type IRouter = InstanceType<typeof Router>;
-
-export interface RouteMatch {
-  route: RouteConfig;
-  params: Record<string, string>;
-  pattern: string;
-}
+export * as NavigationManager from './helpers/navigation-manager.helper.js';
 
 class Router extends Service<Router> {
   private _currentView: View | null = null;
@@ -25,11 +20,16 @@ class Router extends Service<Router> {
   private onNavigate = (data: { path: string }) => this.navigate(data.path);
   private onReload = () => this.reload();
   private _busSubscriptions: Array<() => void> = [];
+  // Bumped by every navigation: one whose guards resolve after a newer navigation started
+  // is dropped instead of rendering over it.
+  private _navId = 0;
+  // False until the first view is rendered: the first load leaves focus to the browser.
+  private _hasRendered = false;
 
-  constructor(private routes: Routes) {
+  constructor(private routes: Nutin.Routes) {
     super();
     this.initializeEventListeners();
-    this.navigate(NavigationManager.getCurrentPath());
+    this.navigate(this.currentLocation());
     this.registerCleanup(this.removeEventListeners);
   }
 
@@ -41,50 +41,101 @@ class Router extends Service<Router> {
     window.removeEventListener('popstate', this.onPopState);
   }
 
+  // Re-renders the current page, so focus isn't moved (see focusView()).
   public async reload(): Promise<void> {
-    const currentRoute = NavigationManager.getCurrentPath();
-    await this.navigate(currentRoute, false);
+    await this.navigateWithMode(this.currentLocation(), 'none', false);
   }
 
   public async navigate(path: string | '', pushState: boolean = true): Promise<void> {
-    const normalizedPath = NavigationManager.normalizePath(path);
+    await this.navigateWithMode(path, pushState ? 'push' : 'none', this._hasRendered);
+  }
+
+  public getCurrentParams(): Record<string, string> {
+    return { ...this._currentParams };
+  }
+
+  public getParam(key: string): string | undefined {
+    return this._currentParams[key];
+  }
+
+  // Path, query and hash of the current URL, as navigate() takes them.
+  private currentLocation(): string {
+    return NavigationManager.getCurrentPath() + window.location.search + window.location.hash;
+  }
+
+  private async navigateWithMode(path: string, mode: HistoryMode, moveFocus: boolean): Promise<void> {
+    const navId = ++this._navId;
+    const isStale = () => navId !== this._navId;
+    const [pathAndQuery = '', hash] = path.split('#');
+    const [rawPath = '', query] = pathAndQuery.split('?');
+    const search = query ? `?${query}` : '';
+    const normalizedPath = NavigationManager.normalizePath(rawPath);
     const currentPath = NavigationManager.getCurrentPath();
-    
+
     // Try to match the route with parameters
     const routeMatch = this.matchRoute(normalizedPath);
 
     if (!routeMatch) {
-      await this.handleNotFound(normalizedPath, currentPath, pushState);
+      await this.handleNotFound(normalizedPath, currentPath, mode, isStale, moveFocus);
       return;
     }
 
     const guardResult = await this.handleGuards(
-      normalizedPath, 
-      routeMatch.route, 
-      routeMatch.params, 
-      pushState
+      normalizedPath,
+      routeMatch.route,
+      routeMatch.params,
+      currentPath,
+      mode,
+      moveFocus
     );
-    
-    if (!guardResult) return;
+
+    if (!guardResult || isStale()) return;
+
+    // Before the current view is torn down: it stays up while a lazy route's chunk loads.
+    const view = await this.resolveView(guardResult.viewConstructor!, NavigationManager.localizedUrl(normalizedPath, search, hash), isStale);
+    if (!view) return;
 
     this._currentView = await ViewRenderManager.transitionOutCurrentView(this._currentView);
     this._currentParams = routeMatch.params;
-    this._currentView = ViewRenderManager.renderNewView(
-      guardResult.viewConstructor!,
-      routeMatch.params
-    );
+
+    // Must run before renderNewView(): a view's onEnter() may rewrite the URL via NavigationManager.replaceState(), 
+    // which acts on whatever history entry is current. This ensures current before onEnter() fires.
+    NavigationManager.updateHistory(normalizedPath, currentPath, mode, hash, search);
+
+    this._currentView = ViewRenderManager.renderNewView(view, routeMatch.params);
 
     NavigationManager.updateDocumentTitle(this._currentView, routeMatch.pattern);
-    NavigationManager.updateHistory(normalizedPath, currentPath, pushState);
-    window.scrollTo({ top: 0 });
+    NavigationManager.scrollToHash(hash);
+    this.afterRender(moveFocus);
   }
 
-  public getCurrentParams(): Record<string, string> {
-    return { ...this._currentParams };
+  // Runs a route's view factory. A sync one behaves as it always did (its errors propagate).
+  // A lazy one is awaited: if it fails to load, recoverFromFailedViewLoad() takes over; if a
+  // newer navigation started meanwhile, the view (already mounted, empty, by its
+  // constructor) is destroyed and dropped.
+  private async resolveView(factory: Nutin.ViewFactory, url: string, isStale: () => boolean): Promise<View | null> {
+    if (isStale()) return null;
+    const result = factory();
+    if (!isPromise(result)) return result;
+
+    let view: View;
+    try {
+      view = await result;
+    } catch (error) {
+      if (!isStale()) NavigationManager.recoverFromFailedViewLoad(url, error);
+      return null;
+    }
+    if (isStale()) {
+      view.destroy();
+      return null;
+    }
+    return view;
   }
 
-  public getParam(key: string): string | undefined {
-    return this._currentParams[key];
+  // After updateDocumentTitle(): focusView() announces document.title when the view has no h1.
+  private afterRender(moveFocus: boolean): void {
+    if (moveFocus && this._currentView) NavigationManager.focusView(this._currentView);
+    this._hasRendered = true;
   }
 
   private initializeEventListeners(): void {
@@ -107,11 +158,13 @@ class Router extends Service<Router> {
   }
 
   private async handlePopState(): Promise<void> {
-    const newLocale = NavigationManager.getCurrentLocale();
-    if (newLocale && newLocale !== I18nService.currentLanguage) {
-      await I18nService.setCurrentLanguage(newLocale as Language);
+    if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
+      const newLocale = NavigationManager.getCurrentLocale();
+      if (newLocale && newLocale !== I18nService.currentLanguage) {
+        await I18nService.setCurrentLanguage(newLocale as Nutin.Language);
+      }
     }
-    this.navigate(NavigationManager.getCurrentPath(), false);
+    this.navigateWithMode(this.currentLocation(), 'none', this._hasRendered);
   }
 
   /**
@@ -120,7 +173,7 @@ class Router extends Service<Router> {
    * - '/users/:id?' matches '/users' and '/users/123'
    * - '/posts/:id' matches '/posts/123' but not '/posts'
    */
-  private matchRoute(path: string): RouteMatch | null {
+  private matchRoute(path: string): Nutin.RouteMatch | null {
     for (const [pattern, routeConfig] of Object.entries(this.routes)) {
       const match = NavigationManager.matchPattern(pattern, path);
       if (match) {
@@ -133,7 +186,9 @@ class Router extends Service<Router> {
   private async handleNotFound(
     normalizedPath: string, 
     currentPath: string, 
-    pushState: boolean
+    mode: HistoryMode,
+    isStale: () => boolean,
+    moveFocus: boolean
   ): Promise<void> {
     const notFoundRoute = this.routes['/404'];
 
@@ -142,21 +197,26 @@ class Router extends Service<Router> {
       return;
     }
 
-    const notFoundConstructor = RouteGuardsManager.getViewConstructor(notFoundRoute);
-    
+    const notFoundFactory = RouteGuardsManager.getViewConstructor(notFoundRoute);
+    const view = await this.resolveView(notFoundFactory, NavigationManager.localizedUrl(normalizedPath), isStale);
+    if (!view) return;
+
     this._currentView = await ViewRenderManager.transitionOutCurrentView(this._currentView);
     this._currentParams = {};
-    this._currentView = ViewRenderManager.renderNewView(notFoundConstructor, {});
+    this._currentView = ViewRenderManager.renderNewView(view, {});
 
     NavigationManager.updateDocumentTitle(this._currentView, '/404');
-    NavigationManager.updateHistory(normalizedPath, currentPath, pushState);
+    NavigationManager.updateHistory(normalizedPath, currentPath, mode);
+    this.afterRender(moveFocus);
   }
 
   private async handleGuards(
     normalizedPath: string,
-    routeConfig: RouteConfig,
+    routeConfig: Nutin.RouteConfig,
     params: Record<string, string>,
-    pushState: boolean
+    currentPath: string,
+    mode: HistoryMode,
+    moveFocus: boolean
   ): Promise<GuardResult | false> {
     const guardResult = await RouteGuardsManager.processRouteGuards(
       routeConfig, 
@@ -166,7 +226,11 @@ class Router extends Service<Router> {
 
     if (!guardResult.allowed) {
       if (guardResult.redirectTo) {
-        await this.navigate(guardResult.redirectTo, pushState);
+        // A guarded URL that's already the current history entry (back/forward,
+        // reload, first load) is replaced by the redirect target, so the address
+        // bar matches what's rendered and Back doesn't land on the guarded URL again.
+        const redirectMode = mode === 'push' && normalizedPath !== currentPath ? 'push' : 'replace';
+        await this.navigateWithMode(guardResult.redirectTo, redirectMode, moveFocus);
       }
       // If no redirect, stay on current route (guard blocked navigation)
       return false;
@@ -176,4 +240,8 @@ class Router extends Service<Router> {
   }
 }
 
-export const AppRouter = (routes: Routes) => Router.getInstance(routes);
+function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  return typeof (value as Promise<T> | null)?.then === 'function';
+}
+
+export const AppRouter = (routes: Nutin.Routes) => Router.getInstance(routes);

package/templates/base/src/index.html.hbs

@@ -2,6 +2,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/x-icon" href="/favicon.ico" />
   </head>
   <body>

package/templates/base/src/styles/_styles.scss.hbs

@@ -1,113 +1 @@
-@use "variables" as *;
-
-/* ===========
-   CSS Reset
-   =========== */
-
-/* Box sizing */
-
-*,
-*::before,
-*::after {
-  box-sizing: border-box;
-}
-
-/* Remove default spacing */
-
-* {
-  margin: 0;
-  padding: 0;
-}
-
-/* Document */
-
-html {
-  font-size: 100%;
-  -webkit-text-size-adjust: 100%;
-}
-
-body {
-  min-height: 100vh;
-  font: inherit;
-  line-height: 1.5;
-}
-
-/* Media */
-
-img,
-picture,
-svg,
-canvas,
-video {
-  display: block;
-  max-width: 100%;
-}
-
-/* Forms */
-
-button,
-input,
-select,
-textarea {
-  font: inherit;
-  color: inherit;
-}
-
-button {
-  background: none;
-  border: none;
-  cursor: pointer;
-}
-
-textarea {
-  resize: vertical;
-}
-
-/* Tables */
-
-table {
-  border-collapse: collapse;
-  border-spacing: 0;
-}
-
-/* Lists */
-
-ul,
-ol {
-  list-style: none;
-}
-
-/* Links */
-
-a {
-  color: inherit;
-  text-decoration: none;
-}
-
-/* Quotes */
-
-blockquote,
-q {
-  quotes: none;
-}
-
-blockquote::before,
-blockquote::after,
-q::before,
-q::after {
-  content: "";
-}
-
-/* Miscellaneous */
-
-hr {
-  border: none;
-}
-
-fieldset {
-  border: none;
-}
-
-:where([hidden]) {
-  display: none !important;
-}
+// Global styles

package/templates/base/src/styles/main.scss.hbs

@@ -1,2 +1,2 @@
-// CSS reset & global styles
+// Global styles
 @use "styles";

package/templates/base/tools/builder/builder.config.js.hbs

@@ -19,6 +19,11 @@ function validateConfig(config) {
 
 validateConfig(nutinConfig);
 
+// `build:prod` passes --prod rather than a NODE_ENV=production prefix, which Windows shells
+// don't understand. Every build step is a separate process that only inherits the env (see
+// runScript), so the flag is turned into NODE_ENV here, for them and for this process.
+if (process.argv.includes('--prod')) process.env.NODE_ENV = 'production';
+
 const wellKnownNonSEORoutes = [
   '/400',
   '/401',
@@ -34,6 +39,7 @@ export const builderConfig = {
   ...nutinConfig.builder,
   isProd: process.env.NODE_ENV === 'production',
   i18n: nutinConfig.i18n,
+  markdownSources: nutinConfig.markdownSources,
   tailwind: nutinConfig.tailwind,
   generateSEO: nutinConfig.generateSEOFiles,
   WELL_KNOWN_NON_SEO_ROUTES: wellKnownNonSEORoutes,

package/templates/base/tools/builder/builder.js.hbs

@@ -1,35 +1,53 @@
 #!/usr/bin/env node
 
 import path from 'path';
-import { print, runScript } from '../utils/index.js';
+import { print, runScript, acquireBuildLock } from '../utils/index.js';
 import { builderConfig } from './builder.config.js';
 
+// Must happen before copy-static.js wipes/recreates dist-build — a second build
+// starting mid-run (a manual build, another dev watcher instance, ...) would
+// otherwise race it. See tools/utils/build-lock.js.
+await acquireBuildLock();
+
 const scriptsDir = path.join(process.cwd(), 'tools', 'builder', 'core');
 
 print.boldHead(`\nStarting build...`);
 
+// runScript forwards env vars but not argv, so -y/--yes (auto-install an opt-in
+// feature's missing dependencies, see utils/ensure-deps.js) is passed through the env.
+if (process.argv.includes('-y') || process.argv.includes('--yes')) process.env.NUTIN_ASSUME_YES = '1';
+
 runScript(path.join(scriptsDir, 'app', 'copy-static.js'), 'Copying files...');
+{{#if markdown}}
+
+runScript(path.join(scriptsDir, 'markdown', 'generate-markdown-pages.js'), 'Compiling Markdown pages...');
+{{/if}}
 
 runScript(path.join(scriptsDir, 'html-index', 'validate-html.js'), 'Processing index.html...');
 runScript(path.join(scriptsDir, 'app', 'validate-routes.js'), 'Validating app routes...');
 
-runScript(path.join(scriptsDir, 'app', 'compile-ts.js'), 'Compiling TypeScript...');
-
 runScript(path.join(scriptsDir, 'html-templates', 'process-html-templates.js'), 'Processing HTML templates...');
+{{#unless (eq lang "js")}}
+// After the templates are merged, so they're type-checked too.
+runScript(path.join(scriptsDir, 'app', 'compile-ts.js'), 'Compiling TypeScript...');
+{{/unless}}
+runScript(path.join(scriptsDir, 'html-templates', 'minify-templates.js'), 'Minifying HTML templates...');
 
 runScript(path.join(scriptsDir, 'styles', 'sass.js'), 'Compiling styles...');
 if (builderConfig.tailwind) runScript(path.join(scriptsDir, 'styles', 'tailwind.js'), 'Compiling Tailwind CSS...');
 
 if (builderConfig.i18n) runScript(path.join(scriptsDir, 'i18n', 'build-i18n.js'), 'Combining locales...');
 
+runScript(path.join(scriptsDir, 'prod-bundle', 'esbuild.js'), 'Running esbuild...');
+
 if (builderConfig.isProd) {
-	runScript(path.join(scriptsDir, 'prod-bundle', 'esbuild.js'), 'Running esbuild...');
-	runScript(path.join(scriptsDir, 'prod-bundle', 'hash-files.js'), 'Hashing files...');
-	runScript(path.join(scriptsDir, 'prod-bundle', 'compress-files.js'), 'Compressing files...');
-	if (builderConfig.generateSEO) runScript(path.join(scriptsDir, 'seo', 'generate-seo-files.js'), 'Generating SEO Files...');
+  runScript(path.join(scriptsDir, 'prod-bundle', 'hash-files.js'), 'Hashing files...');
+  if (builderConfig.generateSEO) runScript(path.join(scriptsDir, 'seo', 'generate-seo-files.js'), 'Generating SEO Files...');
+  // Last, so the prerendered SEO pages, sitemap.xml and robots.txt get compressed too.
+  runScript(path.join(scriptsDir, 'prod-bundle', 'compress-files.js'), 'Compressing files...');
 }
 
-runScript(path.join(scriptsDir, 'finalize-build.js'), 'Finalizing build...')
+runScript(path.join(scriptsDir, 'finalize-build.js'), 'Finalizing build...');
 
 print.boldSuccess(`\nBuild successful!\n`);
 

package/templates/base/tools/builder/core/app/compile-ts.js.hbs

@@ -1,14 +1,89 @@
-import { runCommand, print, errorExit } from "../../../utils/index.js";
+import fs from 'fs';
+import path from 'path';
+import { captureCommand, errorExit } from "../../../utils/index.js";
 import { builderConfig } from '../../builder.config.js';
+import { PATHS } from './paths.js';
+import { readTemplateMap } from '../html-templates/merge-templates.js';
+import { remapTscOutput } from './ts-errors.js';
+import { injectHandlerRefs, stripHandlerRefs } from './handler-refs.js';
+
+// Runs after the .html templates are merged (process-html-templates), on dist-build's copies,
+// so templates are type-checked like the rest of the code. A tsconfig generated there extends
+// the project's: dist-build/src mirrors src, so its include/exclude apply as written.
+const BUILD_TSCONFIG = path.join(PATHS.temp, 'tsconfig.json');
 
 async function compileTS() {
-  // Prod bundles straight from .ts source (see prod-bundle/esbuild.js), so tsc only
-  // needs to type-check there, not emit — emitting would leave a stale, unmerged .js
-  // sibling next to each merged .ts view/component's source.
-  const args = ['--project', 'tsconfig.json'];
+  writeBuildTsconfig();
+
+  // Prod bundles straight from the merged .ts (see prod-bundle/esbuild.js), so tsc only
+  // type-checks there. Dev emits each .js next to its .ts, for the dev bundle and testin-nutin.
+  const args = ['--project', BUILD_TSCONFIG, '--pretty', 'false'];
   if (builderConfig.isProd) args.push('--noEmit');
 
-  await runCommand('tsc', args);
+  // data-event handlers are type-checked through references injected for tsc only, then
+  // removed from the .ts copies the prod bundle is built from (see handler-refs.js).
+  const handlerRefs = await injectHandlerRefs();
+  const { code, output } = await captureCommand('tsc', args);
+  await stripHandlerRefs(handlerRefs);
+  const report = remapTscOutput(output, {
+    cwd: process.cwd(),
+    tempDir: PATHS.temp,
+    templateMap: await readTemplateMap(),
+    handlerRefs,
+  }).trim();
+
+  // On stdout, where tsc itself writes its diagnostics.
+  if (report) console.log(report);
+  if (code !== 0) throw new Error(`tsc exited with code ${code}`);
+}
+
+function writeBuildTsconfig() {
+  const project = readTsconfig(path.resolve('tsconfig.json'));
+  const config = {
+    extends: '../tsconfig.json',
+    compilerOptions: { rootDir: 'src', outDir: 'src' },
+    include: (project.include ?? ['src']).map(toBuildPath),
+    exclude: (project.exclude ?? []).map(toBuildPath),
+  };
+  if (project.files) config.files = project.files.map(toBuildPath);
+  fs.writeFileSync(BUILD_TSCONFIG, JSON.stringify(config, null, 2));
+}
+
+// Paths in src/ are mirrored in dist-build/src; anything else stays where it is, one level up.
+function toBuildPath(entry) {
+  const normalized = entry.replace(/^\.\//, '');
+  return normalized === 'src' || normalized.startsWith('src/') ? normalized : `../${normalized}`;
+}
+
+// tsconfig.json is JSONC: comments and trailing commas are allowed.
+function readTsconfig(file) {
+  const source = fs.readFileSync(file, 'utf-8');
+  let json = '';
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '"') {
+      const end = endOfString(source, i);
+      json += source.slice(i, end);
+      i = end - 1;
+    } else if (ch === '/' && source[i + 1] === '/') {
+      while (i < source.length && source[i] !== '\n') i++;
+      json += '\n';
+    } else if (ch === '/' && source[i + 1] === '*') {
+      i = source.indexOf('*/', i + 2) + 1;
+      if (i === 0) break;
+    } else {
+      json += ch;
+    }
+  }
+  return JSON.parse(json.replace(/,(\s*[}\]])/g, '$1'));
+}
+
+function endOfString(source, start) {
+  for (let i = start + 1; i < source.length; i++) {
+    if (source[i] === '\\') i++;
+    else if (source[i] === '"') return i + 1;
+  }
+  return source.length;
 }
 
 compileTS().catch((err) => {

package/templates/base/tools/builder/core/app/copy-static.js.hbs

@@ -7,7 +7,13 @@ import { builderConfig } from '../../builder.config.js';
 
 async function copyStatic() {
   const extensions = [...BINARY_EXTENSIONS, '.html'];
-  if (builderConfig.isProd) extensions.push('.ts');
+{{#if (eq lang "js")}}
+  // No compile step emits .js here, so sources are copied in dev and prod alike.
+  extensions.push('.js');
+{{else}}
+  // Templates are merged into these copies, then tsc checks them (and emits .js in dev).
+  extensions.push('.ts');
+{{/if}}
 
   // Every build starts from a clean dist-build: a failed/interrupted prior
   // build never gets renamed away by finalize-build.js, so a stale sibling
@@ -23,6 +29,11 @@ async function copyStatic() {
     const files = await getFilesRecursive(PATHS.source, extension);
 
     for (const file of files) {
+{{#if (eq lang "js")}}
+      // Tests import the build output; they must not end up in it.
+      if (file.endsWith('.test.js')) continue;
+
+{{/if}}
       const relative = path.relative(PATHS.source, file);
       const dest = path.join(PATHS.tempSource, relative);