@nutin/cli 2.1.0 → 3.0.0

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

@@ -1,4 +1,4 @@
-import { DomHelper } from '#root/dist/src/core/base-classes/base-component/helpers/dom.helper.js';
+import * as DomHelper from '#root/dist/src/core/base-classes/base-component/helpers/dom.helper.js';
 
 describe('DomHelper', () => {
   let container;
@@ -20,10 +20,19 @@ describe('DomHelper', () => {
     expect(container.contains(el)).toBe(true);
   });
 
-  it('mountElement does nothing when the string selector target is not found', () => {
+  it('mountElement mounts nothing and logs an error when the target is not found', () => {
     const el = document.createElement('span');
-    DomHelper.mountElement(el, '#does-not-exist');
-    expect(el.parentElement).toBe(null);
+    const errorSpy = spyOn(console, 'error').andCallFake(() => {});
+    try {
+      DomHelper.mountElement(el, '#does-not-exist');
+      DomHelper.mountElement(document.createElement('div'), null);
+      expect(el.parentElement).toBe(null);
+      expect(errorSpy.callCount).toBe(2);
+      expect(errorSpy.calls[0][0]).toBe('Nothing to mount <span> into: "#does-not-exist" isn\'t in the page.');
+      expect(errorSpy.calls[1][0]).toContain('its mount target is null');
+    } finally {
+      errorSpy.restore();
+    }
   });
 
   it('mountElement replaces an HTMLElement target with the element', () => {
@@ -39,6 +48,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');
@@ -142,10 +190,63 @@ describe('DomHelper', () => {
     expect(container.querySelectorAll('span').length).toBe(0);
   });
 
+  it('cleanupOptionalContent only touches the given root, attached or not', () => {
+    container.innerHTML = '<p class="outside" data-optional></p>';
+    const detached = document.createElement('div');
+    detached.innerHTML = '<p class="inside" data-optional></p>';
+
+    DomHelper.cleanupOptionalContent(detached);
+
+    expect(detached.querySelector('.inside')).toBe(null);
+    expect(container.querySelector('.outside')).not.toBe(null);
+  });
+
   it('cleanupOptionalContent always strips the data-optional attribute from surviving elements', () => {
     container.innerHTML = '<span data-optional>hello</span>';
     DomHelper.cleanupOptionalContent();
     const span = container.querySelector('span');
     expect(span.hasAttribute('data-optional')).toBe(false);
   });
+
+  it('isInsideNestedComponent is true only below another component root inside the given root', () => {
+    container.innerHTML = '<p class="own"></p><div class="child"><p class="nested"></p></div>';
+    const child = container.querySelector('.child');
+    DomHelper.markComponentRoot(child);
+
+    expect(DomHelper.isInsideNestedComponent(container.querySelector('.own'), container)).toBe(false);
+    expect(DomHelper.isInsideNestedComponent(child, container)).toBe(false);
+    expect(DomHelper.isInsideNestedComponent(container.querySelector('.nested'), container)).toBe(true);
+  });
+
+  it('replacePlaceholder swaps the placeholder for the element', () => {
+    container.innerHTML = '<div class="placeholder"></div>';
+    const el = document.createElement('section');
+
+    DomHelper.replacePlaceholder(el, container.querySelector('.placeholder'));
+
+    expect(container.firstElementChild).toBe(el);
+    expect(container.querySelector('.placeholder')).toBe(null);
+  });
+
+  it('replacePlaceholder uses moveBefore when the element is connected and the browser supports it', () => {
+    const moved = [];
+    Element.prototype.moveBefore = function (node, child) {
+      moved.push(node);
+      this.insertBefore(node, child);
+    };
+
+    try {
+      container.innerHTML = '<div class="placeholder"></div>';
+      const el = document.createElement('section');
+      document.body.appendChild(el);
+
+      DomHelper.replacePlaceholder(el, container.querySelector('.placeholder'));
+
+      expect(moved).toEqual([el]);
+      expect(container.firstElementChild).toBe(el);
+      expect(container.querySelector('.placeholder')).toBe(null);
+    } finally {
+      delete Element.prototype.moveBefore;
+    }
+  });
 });

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

@@ -1,4 +1,4 @@
-import { SecurityHelper, TrustLevel } from "./security.helper.js";
+import * as SecurityHelper from "./security.helper.js";
 
 interface DomElementConfig {
   target: Element | null;
@@ -6,76 +6,150 @@ interface DomElementConfig {
   element: HTMLElement
 }
 
-export class DomHelper {
-  public static mountElement(element: HTMLElement, mountTarget: string | HTMLElement): void {
-    const target = typeof mountTarget === 'string' 
-      ? document.querySelector(mountTarget) 
-      : mountTarget;
+// Element.moveBefore() isn't in TypeScript's DOM lib yet.
+type MovableParent = ParentNode & { moveBefore?: (node: Node, child: Node | null) => void };
 
-    this.appendOrReplace({ target, element, mountTarget });
+// Root element of every component instance, so a parent can tell its own
+// nodes apart from the ones nested components own.
+const componentRoots = new WeakSet<Element>();
+
+export function markComponentRoot(element: HTMLElement): void {
+  componentRoots.add(element);
+}
+
+// True when `el` lives inside another component's root below `root`.
+export function isInsideNestedComponent(el: Element, root: Element): boolean {
+  let current = el.parentElement;
+  while (current && current !== root) {
+    if (componentRoots.has(current)) return true;
+    current = current.parentElement;
+  }
+  return false;
+}
+
+// State-preserving move (focus, iframes, animations, custom elements), only
+// possible when both the node and the target parent are in the document.
+export function canMoveBefore(parent: ParentNode, node: Node): boolean {
+  return typeof (parent as MovableParent).moveBefore === 'function'
+    && parent.isConnected
+    && node.isConnected;
+}
+
+export function moveBefore(parent: ParentNode, node: Node, child: Node | null): void {
+  (parent as MovableParent).moveBefore!(node, child);
+}
+
+// Chrome restarts the CSS animations of a subtree moved into a parent whose style
+// hasn't been computed yet (e.g. created in the same task). Computing it first,
+// before any move dirties it again, keeps them running.
+export function prepareMoveTarget(parent: ParentNode | null, node: Node): void {
+  if (parent instanceof Element && canMoveBefore(parent, node)) {
+    void getComputedStyle(parent).display;
+  }
+}
+
+// Puts an already-mounted element where a placeholder is, moving it without
+// detaching it when the browser supports it.
+export function replacePlaceholder(element: HTMLElement, placeholder: HTMLElement): void {
+  const parent = placeholder.parentNode;
+  if (parent && canMoveBefore(parent, element)) {
+    moveBefore(parent, element, placeholder);
+    placeholder.remove();
+  } else {
+    placeholder.replaceWith(element);
   }
+}
 
-  public static createElement<T extends HTMLElement>(
-    tagName: keyof HTMLElementTagNameMap, 
-    template: string = '',
-    trustLevel?: TrustLevel
-  ): T {
-    const element = document.createElement(tagName) as T;
-    element.innerHTML = SecurityHelper.sanitizeTemplate(template, trustLevel);
-    return element;
+export function mountElement(element: HTMLElement, mountTarget: string | HTMLElement): void {
+  const target = typeof mountTarget === 'string'
+    ? document.querySelector(mountTarget)
+    : mountTarget;
+
+  // Nothing would show up, and nothing else says why (e.g. a misspelled selector, or no #app).
+  if (!(target instanceof HTMLElement)) {
+    const where = typeof mountTarget === 'string' ? `"${mountTarget}" isn't in the page` : `its mount target is ${mountTarget}`;
+    console.error(`Nothing to mount <${element.tagName.toLowerCase()}> into: ${where}.`);
   }
-  
-  public static cleanupOptionalContent(): void {
-    const isEmpty = (el: HTMLElement): boolean => {
-      if (el instanceof HTMLImageElement) {
-        return !el.src || el.src.trim() === "";
-      }
-
-      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-        return !el.value?.trim();
-      }
-
-      if (el instanceof HTMLMediaElement || el instanceof HTMLSourceElement) {
-        return !el.getAttribute("src");
-      }
-
-      const content = el.textContent?.trim();
-      return !content || content === "undefined" || content === "null";
-    };
-
-    const isValueUndefined = (el: HTMLElement): boolean => {
-      const value = el.getAttribute("data-optional");
-      /*
-      A bare/empty data-optional (getAttribute returns "") is a plain marker and
-      defers entirely to isEmpty(el) below rather than forcing removal itself.
-      Only a present-but-blank value (whitespace) or the literal string produced
-      by interpolating an undefined/null expression counts as "value undefined".
-      */
-      if (!value) return false;
-      return (
-        value.trim() === '' ||
-        value === "undefined" ||
-        value === "null"
-      );
+
+  appendOrReplace({ target, element, mountTarget });
+}
+
+export function createElement<T extends HTMLElement>(
+  tagName: keyof HTMLElementTagNameMap, 
+  template: string = '',
+  trustLevel?: Nutin.TrustLevel
+): T {
+  const element = document.createElement(tagName) as T;
+  element.replaceChildren(SecurityHelper.sanitizeToFragment(template, trustLevel));
+  return element;
+}
+
+// Scoped to the rendering component (a detached one included); the document-wide
+// default only serves direct callers.
+export function cleanupOptionalContent(root: ParentNode = document): void {
+  const isEmpty = (el: HTMLElement): boolean => {
+    if (el instanceof HTMLImageElement) {
+      return !el.src || el.src.trim() === "";
+    }
+
+    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+      return !el.value?.trim();
+    }
+
+    if (el instanceof HTMLMediaElement || el instanceof HTMLSourceElement) {
+      return !el.getAttribute("src");
     }
 
-    document.querySelectorAll<HTMLElement>("[data-optional]").forEach(el => {
-      if (isValueUndefined(el) || isEmpty(el)) el.remove();
-      el.removeAttribute("data-optional");
-    });
+    const content = el.textContent?.trim();
+    return !content || content === "undefined" || content === "null";
+  };
+
+  const isValueUndefined = (el: HTMLElement): boolean => {
+    const value = el.getAttribute("data-optional");
+    /*
+    A bare/empty data-optional (getAttribute returns "") is a plain marker and
+    defers entirely to isEmpty(el) below rather than forcing removal itself.
+    Only a present-but-blank value (whitespace) or the literal string produced
+    by interpolating an undefined/null expression counts as "value undefined".
+    */
+    if (!value) return false;
+    return (
+      value.trim() === '' ||
+      value === "undefined" ||
+      value === "null"
+    );
   }
 
-  private static appendOrReplace(config: DomElementConfig) {
-    if (config.target instanceof HTMLElement) {
-      if (typeof config.mountTarget === 'string') {
-        // Append mode
-        config.target.appendChild(config.element);
-      } else {
-        // Replace placeholder mode
-        config.target.replaceWith(config.element);
-      }
+  root.querySelectorAll<HTMLElement>("[data-optional]").forEach(el => {
+    if (isValueUndefined(el) || isEmpty(el)) el.remove();
+    el.removeAttribute("data-optional");
+  });
+}
+
+function appendOrReplace(config: DomElementConfig) {
+  if (config.target instanceof HTMLElement) {
+    if (typeof config.mountTarget === 'string') {
+      // Append mode
+      config.target.appendChild(config.element);
     } else {
-      return;
+      // Replace placeholder mode
+      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.
+function 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.test.js.hbs

@@ -1,4 +1,5 @@
-import { EventHelper } from '#root/dist/src/core/base-classes/base-component/helpers/event.helper.js';
+import * as EventHelper from '#root/dist/src/core/base-classes/base-component/helpers/event.helper.js';
+import * as DomHelper from '#root/dist/src/core/base-classes/base-component/helpers/dom.helper.js';
 
 describe('EventHelper', () => {
   let container;
@@ -56,11 +57,33 @@ describe('EventHelper', () => {
     expect(eventListeners.length).toBe(0);
   });
 
-  it('does nothing when the referenced handler does not exist or is not a function', () => {
-    container.innerHTML = '<button data-event="click:missingHandler"></button>';
+  it('binds nothing and warns when the referenced handler does not exist or is not a function', () => {
+    container.innerHTML = '<button data-event="click:missingHandler"></button><a data-event="click:typo"></a>';
     const component = { missingHandler: 'not-a-function' };
+    const warnSpy = spyOn(console, 'warn').andCallFake(() => {});
+    try {
+      EventHelper.bindEvents(component, container, eventListeners);
+      expect(eventListeners.length).toBe(0);
+      expect(warnSpy.callCount).toBe(2);
+      expect(warnSpy.calls[1][0]).toContain('has no method "typo"');
+    } finally {
+      warnSpy.restore();
+    }
+  });
+
+  it('keeps commas inside quoted literal args', () => {
+    container.innerHTML = `<button data-event="click:handleClick:'a,b',2,&quot;c,d&quot;"></button>`;
+    const button = container.querySelector('button');
+
+    let received = null;
+    const component = {
+      handleClick(...args) { received = args; },
+    };
+
     EventHelper.bindEvents(component, container, eventListeners);
-    expect(eventListeners.length).toBe(0);
+    click(button);
+
+    expect(received).toEqual(['a,b', 2, 'c,d']);
   });
 
   it('tracks each bound listener in the eventListeners array', () => {
@@ -73,6 +96,64 @@ describe('EventHelper', () => {
     expect(eventListeners[0][1]).toBe('click');
   });
 
+  it('skips data-event elements inside a nested component root, which binds its own', () => {
+    container.innerHTML = '<button class="own" data-event="click:toggle"></button><div class="child"><button class="nested" data-event="click:toggle"></button></div>';
+    DomHelper.markComponentRoot(container.querySelector('.child'));
+    let calls = 0;
+    const component = { toggle() { calls++; } };
+
+    EventHelper.bindEvents(component, container, eventListeners);
+    click(container.querySelector('.nested'));
+    expect(calls).toBe(0);
+
+    click(container.querySelector('.own'));
+    expect(calls).toBe(1);
+  });
+
+  it('cancels link navigation, with or without args', () => {
+    container.innerHTML = '<a href="/x" data-event="click:go"></a><a href="/y" data-event="click:go:1"></a>';
+    const component = { go() {} };
+    EventHelper.bindEvents(component, container, eventListeners);
+
+    container.querySelectorAll('a').forEach((a) => {
+      const ev = new window.MouseEvent('click', { bubbles: true, cancelable: true });
+      a.dispatchEvent(ev);
+      expect(ev.defaultPrevented).toBe(true);
+    });
+  });
+
+  it('cancels form submission from a submit event or a submit button click', () => {
+    container.innerHTML = '<form data-event="submit:save"><button type="submit" data-event="click:save"></button></form>';
+    const component = { save() {} };
+    EventHelper.bindEvents(component, container, eventListeners);
+
+    const submit = new window.Event('submit', { bubbles: true, cancelable: true });
+    container.querySelector('form').dispatchEvent(submit);
+    const buttonClick = new window.MouseEvent('click', { bubbles: true, cancelable: true });
+    container.querySelector('button').dispatchEvent(buttonClick);
+
+    expect(submit.defaultPrevented).toBe(true);
+    expect(buttonClick.defaultPrevented).toBe(true);
+  });
+
+  it('keeps the default of other events, args or not (typing, checking a box)', () => {
+    container.innerHTML = '<input class="text" data-event="keydown:onKey:@key"><input class="box" type="checkbox" data-event="click:onToggle:@checked">';
+    let checked = null;
+    const component = { onKey() {}, onToggle(value) { checked = value; } };
+    EventHelper.bindEvents(component, container, eventListeners);
+
+    const keydown = new window.KeyboardEvent('keydown', { key: 'a', bubbles: true, cancelable: true });
+    container.querySelector('.text').dispatchEvent(keydown);
+    const box = container.querySelector('.box');
+    const boxClick = new window.MouseEvent('click', { bubbles: true, cancelable: true });
+    box.dispatchEvent(boxClick);
+
+    expect(keydown.defaultPrevented).toBe(false);
+    expect(boxClick.defaultPrevented).toBe(false);
+    expect(checked).toBe(true);
+    expect(box.checked).toBe(true);
+  });
+
   it('destroyEvents removes every tracked listener', () => {
     container.innerHTML = '<button data-event="click:handleClick"></button>';
     const button = container.querySelector('button');

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

@@ -1,56 +1,106 @@
-import { BaseComponent } from '../base-component.js';
-import { TokenHelper } from './token.helper.js';
-
-export class EventHelper {
-  public static bindEvents(
-    component: BaseComponent,
-    element: HTMLElement,
-    eventListeners: Array<[EventTarget, string, EventListener]>
-  ): void {
-    element.querySelectorAll('[data-event]').forEach(el => {
-      const [eventName, handlerName, ...argParts] = el.getAttribute('data-event')!.split(':');
-      const argsString = argParts.length ? argParts.join(':') : '';
-
-      if (!handlerName || !eventName) return;
-
-      const handler = (component as any)[handlerName];
-
-      if (typeof handler === 'function') {
-        const rawArgs = argsString ? argsString.split(',') : [];
-        const boundHandler = this.createBoundHandler(el, component, handler, rawArgs);
-        this.addEvent(el, eventName, boundHandler, eventListeners);
-      }
-    });
-  }
+import type { BaseComponent } from '../base-component.js';
+import * as DomHelper from './dom.helper.js';
+import * as TokenHelper from './token.helper.js';
 
-  public static destroyEvents(
-    eventListeners: Array<[EventTarget, string, EventListener]>
-  ): void {
-    eventListeners.forEach(([target, event, listener]) => {
-      target.removeEventListener(event, listener);
-    });
-  }
+export function bindEvents(
+  component: BaseComponent,
+  element: HTMLElement,
+  eventListeners: Array<[EventTarget, string, EventListener]>
+): void {
+  element.querySelectorAll('[data-event]').forEach(el => {
+    // A nested component binds its own data-event elements to its own methods.
+    if (DomHelper.isInsideNestedComponent(el, element)) return;
 
-  private static createBoundHandler(
-    el: Element, 
-    component: BaseComponent, 
-    handler: (...args: any[]) => void, 
-    rawArgs: string[]
-  ): EventListener {
-    return (event: Event) => {
-      const resolvedArgs = rawArgs.map(arg => TokenHelper.resolve(arg.trim(), el, event));
-
-      handler.call(component, ...resolvedArgs);
-    };
-  }
+    const [eventName, handlerName, ...argParts] = el.getAttribute('data-event')!.split(':');
+    const argsString = argParts.length ? argParts.join(':') : '';
+
+    if (!handlerName || !eventName) return;
+
+    const handler = (component as any)[handlerName];
+
+    if (typeof handler !== 'function') {
+      // TypeScript builds already fail on a handler the class doesn't have (see handler-refs.js).
+      console.warn(`data-event="${el.getAttribute('data-event')}": ${component.constructor.name} has no method "${handlerName}".`);
+      return;
+    }
 
-  private static addEvent(
-    target: EventTarget,
-    event: string,
-    listener: EventListener,
-    eventListeners: Array<[EventTarget, string, EventListener]>
-  ): void {
-    target.addEventListener(event, listener);
-    eventListeners.push([target, event, listener]);
+    const rawArgs = argsString ? splitArgs(argsString) : [];
+    const boundHandler = createBoundHandler(el, component, handler, rawArgs);
+    addEvent(el, eventName, boundHandler, eventListeners);
+  });
+}
+
+// Splits data-event args on commas, except inside a quoted literal ('a,b' or "a,b").
+function splitArgs(argsString: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let quote: string | null = null;
+  for (const ch of argsString) {
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ',') {
+      args.push(current);
+      current = '';
+      continue;
+    }
+    current += ch;
   }
+  args.push(current);
+  return args;
+}
+
+export function destroyEvents(
+  eventListeners: Array<[EventTarget, string, EventListener]>
+): void {
+  eventListeners.forEach(([target, event, listener]) => {
+    target.removeEventListener(event, listener);
+  });
+}
+
+function createBoundHandler(
+  el: Element,
+  component: BaseComponent,
+  handler: (...args: any[]) => void,
+  rawArgs: string[]
+): EventListener {
+  return (event: Event) => {
+    if (isModifiedAnchorClick(el, event)) return;
+    if (isNavigationDefault(el, event)) event.preventDefault();
+
+    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.
+function 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;
+}
+
+// Only the defaults that would leave the page are cancelled: following a link and
+// submitting a form. Everything else (typing, checking a box, ...) keeps its default.
+function isNavigationDefault(el: Element, event: Event): boolean {
+  if (event.type === 'submit') return true;
+  if (event.type !== 'click') return false;
+  if (el.tagName === 'A') return el.hasAttribute('href');
+  return (el instanceof HTMLButtonElement || el instanceof HTMLInputElement)
+    && el.type === 'submit'
+    && el.form !== null;
+}
+
+function addEvent(
+  target: EventTarget,
+  event: string,
+  listener: EventListener,
+  eventListeners: Array<[EventTarget, string, EventListener]>
+): void {
+  target.addEventListener(event, listener);
+  eventListeners.push([target, event, listener]);
 }