@nutin/cli 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # 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
+
+- `View`'s `viewName` is now a required constructor option. Every `View` subclass must now pass `viewName` explicitly.
+- Removed the `generator` object from `nutin.config.js`. The generator now always scaffolds a stylesheet, and gates locale/test file generation on the existing `i18n` and `testinNutin.includeApp` flags.
+
+### Fixes
+
+- Restored `document.title` updates on route change, regressed silently in 2.0.0's rewrite, default to the view's `viewName`.
+- Fixed leaked-listener/subscription bug that affected every re-rendering component. Previously-mounted child components (single or catalog) are now properly destroyed before a re-render mounts their replacements.
+- `HttpClient`'s constructor `defaultHeaders` are now actually merged into outgoing requests (previously silently dropped — only per-call `config.headers` were sent).
+- `data-optional` elements with literal `"null"` text content (e.g. `<span data-optional>null</span>`) are now correctly removed, matching the existing `"undefined"` handling.
+- `revealGlobals` now restores the element's original `display` value by default (captured automatically by `hideGlobals`), instead of always forcing `block`; an optional second argument still allows an explicit override.
+- A `data-pipe` chain segment with an empty name (e.g. `data-pipe=":arg"`) now logs a warning and is skipped, instead of silently aborting the entire chain with no write-back.
+- Removed a redundant duplicate translation-file fetch on startup when i18n is enabled.
+
 ## 2.0.0
 
 Version 2.0.0 focuses on simplicity and clear APIs over feature accumulation: fewer abstractions, clearer responsibilities, and a more focused API. 

package/README.md

@@ -28,19 +28,16 @@ npx @nutin/cli
 ## Update Nutin
 
 ```bash
-# update Nutin while preserving your changes
+# update to latest version while preserving your changes
 nutin-update
 ```
 
-## Add Docker
+## Add Feature
 
 ```bash
-# ready-to-use Dockerfile for Nutin apps
-nutin-add docker
+nutin-add <feature>
 ```
 
-## Useful links
+## Documentation
 
-- [Nutin website](https://www.nutin.org)
-- [First app tutorial](https://www.nutin.org/tutorial)
-- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)
+- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/API.md)

package/lib/src/create-app/success-message.mjs

@@ -3,12 +3,11 @@ import { PACKAGE_HOMEPAGE } from '../common/package-data.mjs';
 
 export function displaySuccessMessage(answers) {
   const { projectName, packageManager, deployHelper } = answers;
+  print.info(`Visit https://${PACKAGE_HOMEPAGE}`);
+
   print.boldSuccess('\n🎉 Your project is ready!\n');
 
   print.boldInfo('Next steps:');
   print.info(`cd ${projectName}`);
   print.info(`${packageManager} run serve\n`);
-
-  print.boldInfo('Documentation:');
-  print.info(`https://${PACKAGE_HOMEPAGE}\n`);
 }

package/lib/src/update-app/project-updater.mjs

@@ -98,6 +98,12 @@ export class ProjectUpdater {
     }
 
     if (!yes && (toUpdate.length > 0 || toAdd.length > 0)) {
+      if (!process.stdin.isTTY) {
+        print.warn('\n⚠️ Non-interactive shell detected — skipping the confirmation prompt.');
+        print.boldInfo('Re-run with --yes to apply these updates automatically. No files were changed.');
+        return;
+      }
+
       const { proceed } = await inquirer.prompt([
         {
           type: 'confirm',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nutin/cli",
-  "version": "2.0.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
@@ -119,7 +120,6 @@ AppPipeRegistry.register('json');
 
 Central options/tools config (see the inline comments for details):
 - `i18n`, `tailwind`, `generateSEO`, `dockerPorts` — top-level feature toggles (`dockerPorts` only applies once the docker feature is added).
-- `generator.{generateStylesheet, generateLocales, generateTest}` — what the generator scaffolds alongside new elements.
 - `builder.{sass.paths, esbuild}` — build pipeline behavior.
 - `testinNutin.{includeFramework, includeTools, includeApp, jsdomOptions}` — test discovery/environment.
 

package/templates/base/GETTING_STARTED.md.hbs

@@ -3,22 +3,19 @@
 ## Table of contents
 
 - [Project structure](#project-structure)
-- [Running your app](#running-your-app)
-- [Generate components, views and services](#generate-components-views-and-services)
-- [A typical component](#a-typical-component)
-- [Features and configuration](#features-and-configuration)
+- [How do I run my app?](#running-your-app)
+- [How do I generate components, views and services?](#generate-components-views-and-services)
+- [What does a typical component look like?](#a-typical-component)
+- [Options and configuration](#options-and-configuration)
 - [Styling](#styling)
-- [Global layout components](#global-layout-components)
 - [Testing](#testing)
-- [Useful links](#useful-links)
+- [Go further](#go-further)
 
 ## Project structure
 
 ```
-config/   -- configure i18n and SEO files
-
 src/
-  app/
+  app/    -- suggested layout: organize src/app however you like
     components/
     services/
     views/
@@ -33,7 +30,17 @@ tools/    -- build, development, generator and testing
 nutin.config.js   -- features and configuration
 ```
 
-## Running your app
+### Imports
+
+- 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
 # Development
@@ -45,29 +52,22 @@ nutin.config.js   -- features and configuration
 {{packageManager}} run build:prod # build the application for production
 ```
 
-### Imports
-
-Imports must use **relative paths** and end with `.js` extension.
-
-```js
-import { Foo } from 'relative/path/to/foo.js';
-```
-
-## Generate components, views and services
-
-Generated elements are automatically exported from the corresponding barrel file:
-`src/app/<components|views|services>/index.ts`.
+## How do I generate components, views and services?
 
+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/
 ```
 
-## A typical component
+Import generated elements by their file path (e.g. `./views/home/home.view.js`). 
+
+## What does a typical component look like?
 
 ```bash
 components/
@@ -146,29 +146,21 @@ A template can also be written directly inline (skip the `.html` file and the pl
 
 Defining both an inline template and an external `.html` file, or neither, fails the build.
 
-## Features and configuration
+## Options and configuration
 
-Nutin features are enabled in `nutin.config.js`.
+### Main file
 
-### `nutin.config.js`
+`nutin.config.js` - Main Nutin configuration and tool options. See the inline comments for details.
 
-Main Nutin configuration and tool options. See the inline comments for details.
-
-- `tailwind`, `i18n`, `generateSEOFiles` — top-level features, `false` by default.
-- `generator.*` — controls what the generator scaffolds.
+- `tailwind`, `i18n`, `generateSEOFiles` — top-level features, `false` by default. 
+See [Options and features](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/OPTIONS_AND_FEATURES.md).
 - `builder.*` — controls build behavior.
-- `testinNutin.*` — controls TestinNutin.
-
-### `config/seo.json`
+- `testinNutin.*` — controls Nutin's built-in testing toolkit.
 
-- Register your routes' description, title and ogImage here.
-- Data is used to generate static `index.html` per route, `robots.txt`, and `sitemap.xml`.
-- Unused if `nutin.config.js -> generateSEOFiles` is disabled.
+### Specialized files
 
-### `config/languages.json`
-
-- Register supported languages for i18n here.
-- Unused if `nutin.config.js -> i18n` is disabled.
+- `config/seo.json` - with `generateSEOFiles` enabled. Register your routes' description, title and ogImage here.
+- `config/languages.json` - with `i18n` enabled. Register supported languages here.
 
 ## Styling
 
@@ -178,26 +170,11 @@ Main Nutin configuration and tool options. See the inline comments for details.
 
 **Note:** Installing Tailwind CSS dependencies may print `npm warn install-scripts`. This is expected with npm 12's default install-script allowlisting and is safe to ignore.
 
-## Global layout components
-
-If you need components to render outside `<main>` (such as a header or footer), register them with `registerGlobals()` in `main.ts` constructor.
-
-Global components are mounted directly in `<body>` and remain present across route changes. Use `before` for components that should appear before `<main>` and `after` for components that should appear after it.
-
-```ts
-registerGlobals({
-  before: [{ component: HeaderComponent, id: 'header' }],
-  after: [{ component: FooterComponent, id: 'footer' }],
-});
-```
-
-**Note**: `hideGlobals(globalIds: string[])` / `revealGlobals(globalIds: string[])` are exported alongside `registerGlobals` and can be called to toggle visibility of the ids you registered.
-
 ## Testing
 
 You can use any testing tool you prefer for application code.
 
-This project includes TestinNutin, Nutin's lightweight testing toolkit. Nutin itself is tested exclusively with it, and the tests are included in the generated project so you can:
+This project includes [testin-nutin](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/TESTING.md), Nutin's lightweight testing toolkit. Nutin itself is tested exclusively with it, and the tests are included in the generated project so you can:
 - use them as executable documentation;
 - run and modify Nutin's tests when modifying its code.
 
@@ -205,7 +182,7 @@ Run the tests with:
 
 `{{packageManager}} run testin-nutin`
 
-To use TestinNutin for application tests, enable:
+To use testin-nutin for application tests, enable:
 
 ```js
 // nutin.config.js
@@ -218,10 +195,8 @@ testinNutin: {
 import { MyModule } from '#root/dist/src/path/to/my-module.js';
 ```
 
-See **[TestinNutin docs](https://nutin.org/docs/testin-nutin)**.
+## Go further
 
-## Useful links
-
-- [Nutin website](https://www.nutin.org)
+- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs/API.md)
 - [First app tutorial](https://www.nutin.org/tutorial)
-- [Repository documentation](https://github.com/LoisKOUNINEF/nutin/tree/main/docs)
+- [Nutin website](https://www.nutin.org)

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

@@ -3,13 +3,6 @@ export default {
   tailwind: false,         // Enable Tailwind CSS v4
   i18n: false,             // Enable i18n; configure languages in config/languages.json
   generateSEOFiles: false, // Generate per-route HTML, robots.txt and sitemap.xml; configure SEO data in config/seo.json
-  
-  // Components / Views scaffolding
-  generator: {
-    generateStylesheet: false, // Generate a .scss file alongside each component or view
-    generateLocales: false,    // Generate locale files alongside components and views (requires i18n)
-    generateTest: false,       // Generate test files alongside components, views and services (requires testinNutin.includeApp)
-  },
 
   // Build pipeline
   builder: {
@@ -23,7 +16,7 @@ export default {
       bundle: true,
       minify: true,
       sourcemap: false,
-      target: ['es2015'],
+      target: ['es2020'],
       drop: ['console', 'debugger'],
     },
   },

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

@@ -12,7 +12,6 @@ class App {
 document.addEventListener('DOMContentLoaded', async () => {
   if (nutinConfig.i18n) {
     await I18nService.initTranslations();
-    await I18nService.loadTranslations(I18nService.currentLanguage);
   }
   new App();
 });

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/app/views/home/home.view.ts.hbs

@@ -4,6 +4,6 @@ const template = `__TEMPLATE_PLACEHOLDER__`;
 
 export class HomeView extends View {
   constructor() {
-    super({template});
+    super({ template, viewName: 'home' });
   }
 }

package/templates/base/src/app/views/not-found/not-found.view.ts.hbs

@@ -4,7 +4,7 @@ const template = `__TEMPLATE_PLACEHOLDER__`;
 
 export class NotFoundView extends View {
   constructor() {
-    super({template});
+    super({ template, viewName: 'not-found' });
   }
 
   private _handleHome(): void {

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 = [];
@@ -62,6 +86,28 @@ describe('ChildrenHelper', () => {
     expect(children.length).toBe(0);
   });
 
+  it('destroys previously-tracked children and resets the array before mounting new ones on a second call', () => {
+    let destroyCount = 0;
+    element.innerHTML = '<div data-component="widget"></div>';
+    const component = {
+      registerChildren: () => [{
+        selector: 'widget',
+        factory: () => ({ render: () => {}, destroy: () => destroyCount++ }),
+      }],
+    };
+
+    const children = [];
+    ChildrenHelper.addChildren(component, element, children);
+    expect(children.length).toBe(1);
+    expect(destroyCount).toBe(0);
+
+    element.innerHTML = '<div data-component="widget"></div>';
+    ChildrenHelper.addChildren(component, element, children);
+
+    expect(destroyCount).toBe(1);
+    expect(children.length).toBe(1);
+  });
+
   it('destroyChildren calls destroy on every child', () => {
     let destroyCount = 0;
     const children = [

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

@@ -2,10 +2,13 @@ import { BaseComponent, ComponentConfig } from '../base-component.js';
 
 export class ChildrenHelper {
   public static addChildren(
-    component: BaseComponent, 
-    element: HTMLElement, 
+    component: BaseComponent,
+    element: HTMLElement,
     children: BaseComponent[]
   ): void {
+    this.destroyChildren(children);
+    children.length = 0;
+
     const configs: ComponentConfig[] = component.registerChildren();
     configs.forEach(config => {
       element.querySelectorAll(`[data-component="${config.selector}"]`).forEach(el => {

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');
@@ -109,6 +148,12 @@ describe('DomHelper', () => {
     expect(container.querySelector('span')).toBe(null);
   });
 
+  it('cleanupOptionalContent removes an optional element whose textContent is the literal string "null"', () => {
+    container.innerHTML = '<span data-optional>null</span>';
+    DomHelper.cleanupOptionalContent();
+    expect(container.querySelector('span')).toBe(null);
+  });
+
   it('cleanupOptionalContent keeps an optional element with real textContent', () => {
     container.innerHTML = '<span data-optional>hello</span>';
     DomHelper.cleanupOptionalContent();

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

@@ -40,7 +40,7 @@ export class DomHelper {
       }
 
       const content = el.textContent?.trim();
-      return !content || content === "undefined";
+      return !content || content === "undefined" || content === "null";
     };
 
     const isValueUndefined = (el: HTMLElement): boolean => {
@@ -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,