@nutin/cli 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 2.1.1
+
+### Changes
+
+- `src/app` no longer has an imposed structure. 
+
+The generator now creates elements in `src/app/<path>/` instead of `src/app/<type>s/<path>/` (e.g. `generate view user/user-view` → `src/app/user/user-view/`). 
+
+New projects still ship `components/`, `services/` (empty) and `views/` as the suggested layout, so pass the folder explicitly to keep it (`generate component components/my-component`).
+
+- Removed the `src/app/{components,views,services}/index.ts` barrel files from new projects, and the generator no longer appends exports to them. 
+
+Import app elements by their file path.
+
+Import Nutin elements by the framework's barrel (`src/core/index.ts`).
+
+- Sass now compiles every `.scss` file under `src/app` instead of only `src/app/components` and `src/app/views`.
+
+- The generator now exits before writing anything if the target folder already exists and isn't empty, since folder names carry no type suffix.
+
+- Dev builds (`dev`/`serve`/`build`) now bundle with esbuild too, unminified with a sourcemap and `console`/`debugger` kept, so npm runtime dependencies work in dev without import maps or vendoring. tsc's per-file output is still emitted for testin-nutin.
+
+- Sass now resolves `@use "pkg:<package>/<path>"` imports through `node_modules`.
+
+- The default `builder.esbuild.target` in `nutin.config.js` is now `es2020` (was `es2015`), which libraries relying on native `async` functions (e.g. Alpine) require. Existing projects keep their own `nutin.config.js` value.
+
+- Generated SEO HTML now includes `hreflang` alternates (one per language plus `x-default`) when i18n is enabled, `og:type` and `twitter:card` (`summary_large_image`) meta tags, and an absolute `og:image`/`twitter:image` URL (a relative `ogImage` in `config/seo.json` is now prefixed with `baseUrl`).
+
+- The router now supports `#hash` fragments: navigating to `path#id` keeps the hash in the URL and scrolls to the matching element, falling back to the top of the page. The hash is also kept on reload and on language change.
+
+- New `NavigationManager.replaceState(path)` (exported from `core/index.ts`) rewrites the current URL without adding a history entry. The router now updates history before rendering the new view, so a view's `onEnter()` can call it without the change being overwritten.
+
+- Docker feature: `tools/docker/Dockerfile.template` now defaults to Node `24.21.0` (was `22.23.2`) Alpine `3.24` (was `3.20`, end-of-life) for the nginx runtime image (nginx `1.26` → `1.30`).
+
+- Docker feature: in i18n projects, nginx now redirects a bare `/` to the default language (generated into `nginx.conf` through a new `__ROOT_REDIRECT_PLACEHOLDER__` token).
+
+### Fixes
+
+- `generate` with a missing argument now prints its usage message instead of crashing.
+
+- Attributes set on a `data-component` placeholder (`class`, `id`, `aria-*`, `data-*`, …) are now kept on the mounted component's element instead of being dropped. Classes are merged with the component's own.
+
+- Builds now take a lock (`.build-lock/`, gitignored) before touching `dist-build`, so concurrent builds (a manual build during `dev`, or stray watcher processes) no longer corrupt each other's output.
+
+- The dev watcher no longer drops a file change made while a rebuild is running. It now rebuilds again once the current build finishes.
+
+- Stopping `dev` now kills the whole process group of live-server and the watcher (including an in-flight build), so no orphaned watcher processes are left behind. On Windows, the process tree is killed with `taskkill` instead.
+
+- SSR now renders views into a real `<main id="app">`, so unset `data-optional` fields are removed from prerendered HTML instead of leaking the literal text `undefined`.
+
+- Ctrl/Cmd/Shift/Alt-clicks and middle-clicks on `<a href>` elements with a `data-event` click handler now fall through to the browser's native behaviour (e.g. open in a new tab), instead of being intercepted.
+
+- Docker feature: nginx now issues relative redirects (`absolute_redirect off`), so the trailing-slash redirect on prerendered routes no longer leaks the container's internal port or scheme behind a proxy. A route directory without its own `index.html` now serves the SPA shell instead of a 403.
+
 ## 2.1.0
 
 ### Breaking Changes

package/README.md

@@ -28,7 +28,7 @@ npx @nutin/cli
 ## Update Nutin
 
 ```bash
-# update Nutin while preserving your changes
+# update to latest version while preserving your changes
 nutin-update
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nutin/cli",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "The structure of a framework. The freedom of vanilla.",
   "preferGlobal": true,
   "main": "lib/index.mjs",
@@ -17,7 +17,7 @@
     "minor": "npm version minor -m 'CI/CD: Bump version to %s'",
     "major": "npm version major -m 'CI/CD: Bump version to %s'",
     "test": "echo \"Error: no test specified\" && exit 1",
-    "publish": "npm publish --access public"
+    "release": "npm publish --access public"
   },
   "keywords": [
     "Nutin",
@@ -42,10 +42,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/loiskouninef/nutin.git"
+    "url": "git+https://github.com/LoisKOUNINEF/nutin.git"
   },
   "bugs": {
-    "url": "https://github.com/loiskouninef/nutin/issues"
+    "url": "https://github.com/LoisKOUNINEF/nutin/issues"
   },
   "homepage": "www.nutin.org"
 }

package/templates/base/.gitignore.hbs

@@ -7,6 +7,7 @@ pnpm-debug.log*
 
 /dist/
 /dist-build/
+/.build-lock/
 /coverage/
 
 # Generated by "validate-docker" (run via docker:build) from tools/docker/*.template — only present when the docker feature is added

package/templates/base/AGENTS.md.hbs

@@ -19,13 +19,14 @@ nutin.config.js   build/feature config — see below
 
 - Favor small, composable components.
 - One `View` = one route.
-- Import everything from barrel files (`core/index.js`, `components/index.js`, `views/index.js`, `services/index.js`) — do not deep-import.
+- Import framework code from the `core/index.js` barrel — do not deep-import into `core/`. App elements have no barrels: import them by file path.
+- `src/app/` layout is free; `components/`, `views/`, `services/` is the default suggestion.
 
 ## Commands
 
 - Serve: `{{packageManager}} run serve` (build + serve), `{{packageManager}} run serve:only` (no rebuild), `{{packageManager}} run dev` (watch mode).
 - Build: `{{packageManager}} run build` (dev) or `{{packageManager}} run build:prod` (production).
-- Generate: `{{packageManager}} run generate ELEMENT ELEMENT_NAME` (`ELEMENT` = `component`/`view`/`service`, supports nested paths, updates the nearest `index.ts` barrel).
+- Generate: `{{packageManager}} run generate ELEMENT ELEMENT_NAME` (`ELEMENT` = `component`/`view`/`service`; `ELEMENT_NAME` may be a nested path, generated in `src/app/<path>/`; fails if that folder already exists and isn't empty).
 - Test: `{{packageManager}} run testin-nutin` (build + run), `{{packageManager}} run testin-nutin:only` (no rebuild), `{{packageManager}} run testin-nutin:watch`.
 
 ## Base classes

package/templates/base/GETTING_STARTED.md.hbs

@@ -15,7 +15,7 @@
 
 ```
 src/
-  app/
+  app/    -- suggested layout: organize src/app however you like
     components/
     services/
     views/
@@ -32,12 +32,14 @@ nutin.config.js   -- features and configuration
 
 ### Imports
 
-Imports use **relative paths** and end with `.js` extension.
+- Imports use **relative paths** and end with `.js` extension.
 
 ```js
 import { Foo } from 'relative/path/to/foo.js';
 ```
 
+- Use Nutin's code barrel file (`src/core/index.js`) to import Nutin's modules.
+
 ## How do I run my app?
 
 ```bash
@@ -52,18 +54,19 @@ import { Foo } from 'relative/path/to/foo.js';
 
 ## How do I generate components, views and services?
 
-Generated elements are automatically exported from the corresponding barrel file:
-`src/app/<components|views|services>/index.ts`.
-
+Elements are generated in `src/app/<path>/`, so you choose the project structure. The generator stops if the target folder already exists and isn't empty.
 
 ```bash
-{{packageManager}} run generate <component|view|service> ELEMENT_NAME
+{{packageManager}} run generate <component|view|service> PATH/TO/ELEMENT_NAME
 
 # Examples
-{{packageManager}} run generate component my-component # Target dir: src/app/components/my-component/
-{{packageManager}} run generate component path/to/my-component/ # Target dir: src/app/components/path/to/my-component/
+{{packageManager}} run generate component components/my-component # Target dir: src/app/components/my-component/
+{{packageManager}} run generate view user/user-view                # Target dir: src/app/user/user-view/
+{{packageManager}} run generate service user/user-service          # Target dir: src/app/user/user-service/
 ```
 
+Import generated elements by their file path (e.g. `./views/home/home.view.js`). 
+
 ## What does a typical component look like?
 
 ```bash

package/templates/base/nutin.config.js.hbs

@@ -16,7 +16,7 @@ export default {
       bundle: true,
       minify: true,
       sourcemap: false,
-      target: ['es2015'],
+      target: ['es2020'],
       drop: ['console', 'debugger'],
     },
   },

package/templates/base/src/app/routes.ts.hbs

@@ -1,5 +1,6 @@
 import { Routes } from '../core/index.js';
-import { HomeView, NotFoundView } from './views/index.js';
+import { HomeView } from './views/home/home.view.js';
+import { NotFoundView } from './views/not-found/not-found.view.js';
 
 export const appRoutes: Routes = {
   '/': () => new HomeView(),

package/templates/base/src/core/base-classes/base-component/helpers/children.helper.test.js.hbs

@@ -1,4 +1,5 @@
 import { ChildrenHelper } from '#root/dist/src/core/base-classes/base-component/helpers/children.helper.js';
+import { BaseComponent } from '#root/dist/src/core/index.js';
 
 describe('ChildrenHelper', () => {
   let element;
@@ -55,6 +56,29 @@ describe('ChildrenHelper', () => {
     expect(children.length).toBe(2);
   });
 
+  it('keeps the placeholder attributes (except data-component) on the mounted child element', () => {
+    class Widget extends BaseComponent {
+      generateTemplate() { return '<p>widget</p>'; }
+    }
+    element.innerHTML = '<div data-component="widget" class="my-class" id="my-widget"></div>';
+    const component = {
+      registerChildren: () => [{
+        selector: 'widget',
+        factory: (el) => new Widget({ mountTarget: el }),
+      }],
+    };
+
+    const children = [];
+    ChildrenHelper.addChildren(component, element, children);
+
+    const childEl = children[0].getElement();
+    expect(element.contains(childEl)).toBe(true);
+    expect(childEl.classList.contains('my-class')).toBe(true);
+    expect(childEl.id).toBe('my-widget');
+    expect(childEl.hasAttribute('data-component')).toBe(false);
+    expect(childEl.innerHTML).toBe('<p>widget</p>');
+  });
+
   it('does nothing when there are no registerChildren', () => {
     const component = { registerChildren: () => [] };
     const children = [];

package/templates/base/src/core/base-classes/base-component/helpers/dom.helper.test.js.hbs

@@ -39,6 +39,45 @@ describe('DomHelper', () => {
     expect(container.contains(el)).toBe(true);
   });
 
+  it('mountElement carries the placeholder attributes onto the element, merging classes', () => {
+    const placeholder = document.createElement('div');
+    placeholder.className = 'my-class other-class';
+    placeholder.id = 'foo';
+    placeholder.setAttribute('aria-label', 'Label');
+    placeholder.setAttribute('data-extra', 'bar');
+    container.appendChild(placeholder);
+
+    const el = document.createElement('span');
+    el.className = 'own-class';
+    DomHelper.mountElement(el, placeholder);
+
+    expect(el.classList.contains('own-class')).toBe(true);
+    expect(el.classList.contains('my-class')).toBe(true);
+    expect(el.classList.contains('other-class')).toBe(true);
+    expect(el.id).toBe('foo');
+    expect(el.getAttribute('aria-label')).toBe('Label');
+    expect(el.getAttribute('data-extra')).toBe('bar');
+  });
+
+  it('mountElement does not carry data-component over from the placeholder', () => {
+    const placeholder = document.createElement('div');
+    placeholder.setAttribute('data-component', 'widget');
+    container.appendChild(placeholder);
+
+    const el = document.createElement('span');
+    DomHelper.mountElement(el, placeholder);
+
+    expect(el.hasAttribute('data-component')).toBe(false);
+  });
+
+  it('mountElement leaves the element attributes untouched in append mode', () => {
+    container.className = 'container-class';
+    const el = document.createElement('span');
+    DomHelper.mountElement(el, '#mount-target');
+
+    expect(el.attributes.length).toBe(0);
+  });
+
   it('createElement creates an element with the given tag name', () => {
     const el = DomHelper.createElement('section');
     expect(el.tagName).toBe('SECTION');

package/templates/base/src/core/base-classes/base-component/helpers/dom.helper.ts.hbs

@@ -72,10 +72,24 @@ export class DomHelper {
         config.target.appendChild(config.element);
       } else {
         // Replace placeholder mode
+        this.copyAttributes(config.target, config.element);
         config.target.replaceWith(config.element);
       }
     } else {
       return;
     }
   }
+
+  // Carries placeholder attributes (class, id, aria-*, data-*...) onto the mounted
+  // element. data-component is skipped so an ancestor's child lookup can't re-match it.
+  private static copyAttributes(from: HTMLElement, to: HTMLElement): void {
+    Array.from(from.attributes).forEach(attr => {
+      if (attr.name === 'data-component') return;
+      if (attr.name === 'class') {
+        to.classList.add(...Array.from(from.classList));
+        return;
+      }
+      to.setAttribute(attr.name, attr.value);
+    });
+  }
 }

package/templates/base/src/core/base-classes/base-component/helpers/event.helper.ts.hbs

@@ -32,18 +32,29 @@ export class EventHelper {
   }
 
   private static createBoundHandler(
-    el: Element, 
-    component: BaseComponent, 
-    handler: (...args: any[]) => void, 
+    el: Element,
+    component: BaseComponent,
+    handler: (...args: any[]) => void,
     rawArgs: string[]
   ): EventListener {
     return (event: Event) => {
+      if (this.isModifiedAnchorClick(el, event)) return;
+
       const resolvedArgs = rawArgs.map(arg => TokenHelper.resolve(arg.trim(), el, event));
 
       handler.call(component, ...resolvedArgs);
     };
   }
 
+  // Lets a real <a href> fall through to native browser behavior (open in new tab, etc.)
+  // on a modified or non-primary click, instead of always intercepting via preventDefault.
+  private static isModifiedAnchorClick(el: Element, event: Event): boolean {
+    if (event.type !== 'click' || el.tagName !== 'A' || !el.getAttribute('href')) return false;
+
+    const mouseEvent = event as MouseEvent;
+    return mouseEvent.ctrlKey || mouseEvent.metaKey || mouseEvent.shiftKey || mouseEvent.altKey || mouseEvent.button !== 0;
+  }
+
   private static addEvent(
     target: EventTarget,
     event: string,

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

@@ -39,6 +39,40 @@ describe('NavigationManager', () => {
     window.history.pushState = originalPushState;
   });
 
+  it('replaceState calls history.replaceState (not pushState) with the locale-prefixed path', () => {
+    const originalReplaceState = window.history.replaceState;
+    const originalPushState = window.history.pushState;
+    let pushCalled = false;
+    let replaceArgs = null;
+
+    window.history.pushState = () => { pushCalled = true; };
+    window.history.replaceState = (state, title, url) => { replaceArgs = url; };
+
+    try {
+      NavigationManager.replaceState('/section/first-page');
+      expect(replaceArgs).toBe('/section/first-page');
+      expect(pushCalled).toBe(false);
+    } finally {
+      window.history.replaceState = originalReplaceState;
+      window.history.pushState = originalPushState;
+    }
+  });
+
+  it('replaceState preserves an existing hash fragment', () => {
+    const originalReplaceState = window.history.replaceState;
+    window.history.pushState({}, '', '/section#some-heading');
+    let replaceArgs = null;
+    window.history.replaceState = (state, title, url) => { replaceArgs = url; };
+
+    try {
+      NavigationManager.replaceState('/section/first-page');
+      expect(replaceArgs).toBe('/section/first-page#some-heading');
+    } finally {
+      window.history.replaceState = originalReplaceState;
+      window.history.pushState({}, '', '/');
+    }
+  });
+
   it('should return current path from location', () => {
     // This test assumes a DOM-like environment
     const currentPath = window.location.pathname;

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

@@ -48,14 +48,36 @@ export class NavigationManager {
   public static updateHistory(
     normalizedPath: string,
     currentPath: string,
-    pushState: boolean
+    pushState: boolean,
+    hash?: string
   ): void {
-    const localizedPath = this.addLocalePrefix(normalizedPath);
-    if (pushState && window.location.pathname !== localizedPath) {
+    const localizedPath = this.addLocalePrefix(normalizedPath) + (hash ? `#${hash}` : '');
+    const currentUrl = window.location.pathname + window.location.hash;
+    if (pushState && currentUrl !== localizedPath) {
       window.history.pushState({}, '', localizedPath);
     }
   }
 
+  // Rewrites the current history entry's URL to match content already rendered
+  // (e.g. a route that fell back to a default sub-page) without adding a
+  // new back/forward-navigable entry.
+  public static replaceState(path: string): void {
+    const localizedPath = this.addLocalePrefix(path) + window.location.hash;
+    window.history.replaceState({}, '', localizedPath);
+  }
+
+  // Scrolls to the element matching `hash` (a bare fragment, no leading "#") if it
+  // exists; falls back to the top of the page otherwise (no hash, or a stale/broken
+  // id) — matches the browser's own native fallback for an unresolvable fragment.
+  public static scrollToHash(hash?: string): void {
+    const target = hash ? document.getElementById(hash) : null;
+    if (target) {
+      target.scrollIntoView({ block: 'start' });
+    } else {
+      window.scrollTo({ top: 0 });
+    }
+  }
+
   public static getCurrentPath(): string {
     return this.normalizePath(window.location.pathname);
   }

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

@@ -60,6 +60,21 @@ describe('Router', () => {
     ]);
   });
 
+  it('navigate() applies a view\'s onEnter() history rewrite without it being overwritten by the router\'s own history update', async () => {
+    const home = makeView('home');
+    const section = makeView('section');
+    section.onEnter = () => {
+      section.calls.push(['onEnter']);
+      window.history.replaceState({}, '', '/section/first-page');
+    };
+    router = AppRouter({ '/': () => home, '/section': () => section });
+    await flushPromises();
+
+    await router.navigate('/section');
+
+    expect(window.location.pathname).toBe('/section/first-page');
+  });
+
   it('navigate() passes matched route params to the rendered view', async () => {
     const home = makeView('home');
     const userView = makeView('user');

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

@@ -6,6 +6,7 @@ import { NavigationManager } from './helpers/navigation-manager.helper.js';
 
 // centralized export
 export { Routes, RouteGuard } from './helpers/route-guard-manager.helper.js';
+export { NavigationManager } from './helpers/navigation-manager.helper.js';
 
 /**
  * IRouter is a type alias for the instance of Router, not a true interface 
@@ -29,7 +30,7 @@ class Router extends Service<Router> {
   constructor(private routes: Routes) {
     super();
     this.initializeEventListeners();
-    this.navigate(NavigationManager.getCurrentPath());
+    this.navigate(NavigationManager.getCurrentPath() + window.location.hash);
     this.registerCleanup(this.removeEventListeners);
   }
 
@@ -43,13 +44,14 @@ class Router extends Service<Router> {
 
   public async reload(): Promise<void> {
     const currentRoute = NavigationManager.getCurrentPath();
-    await this.navigate(currentRoute, false);
+    await this.navigate(currentRoute + window.location.hash, false);
   }
 
   public async navigate(path: string | '', pushState: boolean = true): Promise<void> {
-    const normalizedPath = NavigationManager.normalizePath(path);
+    const [rawPath = '', hash] = path.split('#');
+    const normalizedPath = NavigationManager.normalizePath(rawPath);
     const currentPath = NavigationManager.getCurrentPath();
-    
+
     // Try to match the route with parameters
     const routeMatch = this.matchRoute(normalizedPath);
 
@@ -59,24 +61,30 @@ class Router extends Service<Router> {
     }
 
     const guardResult = await this.handleGuards(
-      normalizedPath, 
-      routeMatch.route, 
-      routeMatch.params, 
+      normalizedPath,
+      routeMatch.route,
+      routeMatch.params,
       pushState
     );
-    
+
     if (!guardResult) return;
 
     this._currentView = await ViewRenderManager.transitionOutCurrentView(this._currentView);
     this._currentParams = routeMatch.params;
+
+    // Must run before renderNewView(): a view's onEnter() may rewrite the URL via
+    // NavigationManager.replaceState (e.g. canonicalizing a bare route to a default
+    // sub-page), which acts on whatever history entry is current — so that entry needs
+    // to already be this route's, not the previous view's, before onEnter() fires.
+    NavigationManager.updateHistory(normalizedPath, currentPath, pushState, hash);
+
     this._currentView = ViewRenderManager.renderNewView(
       guardResult.viewConstructor!,
       routeMatch.params
     );
 
     NavigationManager.updateDocumentTitle(this._currentView, routeMatch.pattern);
-    NavigationManager.updateHistory(normalizedPath, currentPath, pushState);
-    window.scrollTo({ top: 0 });
+    NavigationManager.scrollToHash(hash);
   }
 
   public getCurrentParams(): Record<string, string> {
@@ -111,7 +119,7 @@ class Router extends Service<Router> {
     if (newLocale && newLocale !== I18nService.currentLanguage) {
       await I18nService.setCurrentLanguage(newLocale as Language);
     }
-    this.navigate(NavigationManager.getCurrentPath(), false);
+    this.navigate(NavigationManager.getCurrentPath() + window.location.hash, false);
   }
 
   /**

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";