@nutin/cli 2.1.0 → 3.0.0

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

@@ -1,4 +1,4 @@
-import { BaseComponent, AppEventBus } from '#root/dist/src/core/index.js';
+import { BaseComponent, AppEventBus, AppPipeRegistry } from '#root/dist/src/core/index.js';
 
 class TestComponent extends BaseComponent {
   constructor(options = {}, hooks = {}) {
@@ -37,6 +37,87 @@ class TestComponent extends BaseComponent {
   }
 }
 
+class InputChild extends BaseComponent {
+  constructor(options) {
+    super(options);
+    this.renders = 0;
+    this.keptCount = 0;
+  }
+  generateTemplate() { return '<input>'; }
+  onBeforeRender() { this.renders++; }
+  onKept() { this.keptCount++; }
+}
+
+class KeepingParent extends BaseComponent {
+  constructor(options = {}, childTemplate = '<div data-component="child"></div>') {
+    super(options);
+    this.childTemplate = childTemplate;
+    this.keep = 'a';
+    this.created = [];
+  }
+  generateTemplate() { return `<h1>parent</h1>${this.childTemplate}`; }
+  registerChildren() {
+    return [{
+      selector: 'child',
+      keep: this.keep,
+      factory: (el) => {
+        const child = new InputChild({ mountTarget: el });
+        this.created.push(child);
+        return child;
+      },
+    }];
+  }
+}
+
+class LoggingChild extends BaseComponent {
+  constructor(options, log, name, hooks = {}) {
+    super(options);
+    this.log = log;
+    this.name = name;
+    this.hooks = hooks;
+    this.keptCount = 0;
+  }
+  generateTemplate() { return this.hooks.template ?? `<input class="${this.name}">`; }
+  registerChildren() { return this.hooks.children?.(this) ?? []; }
+  onBeforeRender() { this.log.push(`${this.name}:render`); }
+  onKept() {
+    this.keptCount++;
+    this.log.push(`${this.name}:kept`);
+    this.hooks.onKept?.(this);
+  }
+}
+
+class LoggingParent extends BaseComponent {
+  constructor(log, hooks = {}) {
+    super({});
+    this.log = log;
+    this.hooks = hooks;
+    this.children = [];
+  }
+  generateTemplate() { return this.hooks.template ?? '<div data-component="a"></div><div data-component="b"></div>'; }
+  registerChildren() {
+    return this.hooks.children?.(this) ?? ['a', 'b'].map(name => ({
+      selector: name,
+      keep: name,
+      factory: (el) => {
+        const child = new LoggingChild({ mountTarget: el }, this.log, name, this.hooks.childHooks?.[name]);
+        this.children.push(child);
+        return child;
+      },
+    }));
+  }
+  compose() {
+    this.log.push('parent:compose');
+    if (this.hooks.compose) this.hooks.compose(this);
+    else super.compose();
+  }
+  hydrate() {
+    this.log.push('parent:hydrate');
+    super.hydrate();
+  }
+  onAfterRender() { this.log.push('parent:afterRender'); }
+}
+
 describe('BaseComponent', () => {
   let app;
 
@@ -155,4 +236,383 @@ describe('BaseComponent', () => {
     expect(configs.length).toBe(1);
     component.destroy();
   });
+
+  it('render() keeps a child with a keep value, its typed value and focus across a parent re-render, and calls onKept() on it', () => {
+    const parent = new KeepingParent();
+    parent.render();
+    const [child] = parent.created;
+    const input = child.getElement().querySelector('input');
+    input.value = 'typed';
+    input.focus();
+
+    parent.render();
+
+    expect(parent.created.length).toBe(1);
+    expect(child.renders).toBe(1);
+    expect(child.keptCount).toBe(1);
+    expect(parent.getElement().contains(input)).toBe(true);
+    expect(input.value).toBe('typed');
+    expect(document.activeElement).toBe(input);
+    parent.destroy();
+  });
+
+  it('render() recreates a child with a keep value whose key changed and does not call onKept() on the new one', () => {
+    const parent = new KeepingParent();
+    parent.render();
+    parent.keep = 'b';
+
+    parent.render();
+
+    expect(parent.created.length).toBe(2);
+    expect(parent.created[0].keptCount).toBe(0);
+    expect(parent.created[1].keptCount).toBe(0);
+    expect(parent.getElement().contains(parent.created[0].getElement())).toBe(false);
+    parent.destroy();
+  });
+
+  it('destroy() destroys kept children too', () => {
+    const parent = new KeepingParent();
+    parent.render();
+    parent.render();
+    const childEl = parent.created[0].getElement();
+
+    parent.destroy();
+
+    expect(childEl.isConnected).toBe(false);
+  });
+
+  it('render() keeps keepBy catalog items that did not change and recreates the ones that did', () => {
+    class Item extends BaseComponent {
+      constructor(el, data) {
+        super({ mountTarget: el });
+        this.data = data;
+      }
+      generateTemplate() { return `<span>${this.data.name}</span>`; }
+    }
+    class List extends BaseComponent {
+      constructor() {
+        super({});
+        this.items = [{ id: 1, name: 'a' }, { id: 2, name: 'b' }];
+      }
+      generateTemplate() { return '<ul data-catalog="list"></ul>'; }
+      registerChildren() {
+        return this.createCatalogComponents({
+          items: this.items,
+          selector: 'list',
+          elementName: 'item',
+          elementTag: 'li',
+          component: Item,
+          keepBy: (item) => item.id,
+        });
+      }
+    }
+    const list = new List();
+    list.render();
+    const [first, second] = Array.from(list.getElement().querySelectorAll('span'));
+
+    list.items = [{ id: 0, name: 'new' }, { id: 1, name: 'a' }, { id: 2, name: 'changed' }];
+    list.render();
+
+    const spans = Array.from(list.getElement().querySelectorAll('span'));
+    expect(spans.map(span => span.textContent)).toEqual(['new', 'a', 'changed']);
+    expect(spans[1]).toBe(first);
+    expect(spans[2]).not.toBe(second);
+    expect(Array.from(list.getElement().querySelectorAll('li')).map(li => li.dataset.index)).toEqual(['0', '1', '2']);
+    list.destroy();
+  });
+
+  it('render() does not pipe a kept child\'s content again', () => {
+    silenceConsole('warn', () => AppPipeRegistry.register('baseComponentExclaim', (value) => `${value}!`));
+    class PipedChild extends BaseComponent {
+      generateTemplate() { return '<span data-pipe="baseComponentExclaim">hi</span>'; }
+    }
+    class Parent extends BaseComponent {
+      generateTemplate() { return '<div data-component="child"></div>'; }
+      registerChildren() {
+        return [{ selector: 'child', keep: 'c', factory: (el) => new PipedChild({ mountTarget: el }) }];
+      }
+    }
+    const parent = new Parent({});
+
+    parent.render();
+    parent.render();
+
+    expect(parent.getElement().querySelector('span').textContent).toBe('hi!');
+    parent.destroy();
+  });
+
+  it('render() parks kept children with moveBefore and leaves no parking element behind', () => {
+    const moved = [];
+    Element.prototype.moveBefore = function (node, child) {
+      moved.push(node);
+      this.insertBefore(node, child);
+    };
+
+    try {
+      const parent = new KeepingParent();
+      parent.render();
+      const childEl = parent.created[0].getElement();
+      const bodyChildren = document.body.children.length;
+
+      parent.render();
+
+      expect(moved).toEqual([childEl, childEl]);
+      expect(parent.getElement().contains(childEl)).toBe(true);
+      expect(document.body.children.length).toBe(bodyChildren);
+      parent.destroy();
+    } finally {
+      delete Element.prototype.moveBefore;
+    }
+  });
+
+  it('onKept() runs once per parent re-render, for every kept child', () => {
+    const parent = new LoggingParent([]);
+    parent.render();
+    parent.render();
+    parent.render();
+
+    expect(parent.children.length).toBe(2);
+    expect(parent.children.map(child => child.keptCount)).toEqual([2, 2]);
+    parent.destroy();
+  });
+
+  it('onKept() runs after compose() with the child back in place, before the parent hydrates and runs onAfterRender()', () => {
+    const log = [];
+    let connectedWhenKept;
+    const parent = new LoggingParent(log, {
+      childHooks: { a: { onKept: (child) => { connectedWhenKept = parent.getElement().contains(child.getElement()) && child.getElement().isConnected; } } },
+    });
+    parent.render();
+    log.length = 0;
+
+    parent.render();
+
+    expect(log).toEqual(['parent:compose', 'a:kept', 'b:kept', 'parent:hydrate', 'parent:afterRender']);
+    expect(connectedWhenKept).toBe(true);
+    parent.destroy();
+  });
+
+  it('onKept() is not called on a child created by the same render, even when a sibling is kept', () => {
+    const log = [];
+    let bKeep = 'b';
+    const parent = new LoggingParent(log, {
+      children: (self) => [
+        { selector: 'a', keep: 'a', factory: (el) => { const c = new LoggingChild({ mountTarget: el }, log, 'a'); self.children.push(c); return c; } },
+        { selector: 'b', keep: bKeep, factory: (el) => { const c = new LoggingChild({ mountTarget: el }, log, 'b'); self.children.push(c); return c; } },
+      ],
+    });
+    parent.render();
+    bKeep = 'b2';
+    log.length = 0;
+
+    parent.render();
+
+    expect(log.filter(entry => entry.endsWith(':kept'))).toEqual(['a:kept']);
+    expect(log.filter(entry => entry.endsWith(':render'))).toEqual(['b:render']);
+    parent.destroy();
+  });
+
+  it('onKept() is called on unchanged keepBy catalog items only', () => {
+    const kept = [];
+    class Item extends BaseComponent {
+      constructor(el, data) {
+        super({ mountTarget: el });
+        this.data = data;
+      }
+      generateTemplate() { return `<span>${this.data.name}</span>`; }
+      onKept() { kept.push(this.data.name); }
+    }
+    class List extends BaseComponent {
+      constructor() {
+        super({});
+        this.items = [{ id: 1, name: 'a' }, { id: 2, name: 'b' }, { id: 3, name: 'c' }];
+      }
+      generateTemplate() { return '<ul data-catalog="list"></ul>'; }
+      registerChildren() {
+        return this.createCatalogComponents({
+          items: this.items, selector: 'list', elementName: 'item', component: Item, keepBy: (item) => item.id,
+        });
+      }
+    }
+    const list = new List();
+    list.render();
+    list.items = [{ id: 4, name: 'new' }, { id: 1, name: 'a' }, { id: 2, name: 'changed' }];
+
+    list.render();
+
+    expect(kept).toEqual(['a']);
+    list.destroy();
+  });
+
+  it('onKept() is not called on children of a kept child, which are left untouched', () => {
+    const log = [];
+    const parent = new LoggingParent(log, {
+      template: '<div data-component="a"></div>',
+      children: (self) => [{
+        selector: 'a',
+        keep: 'a',
+        factory: (el) => {
+          const child = new LoggingChild({ mountTarget: el }, log, 'a', {
+            template: '<div data-component="inner"></div>',
+            children: () => [{ selector: 'inner', keep: 'inner', factory: (innerEl) => new LoggingChild({ mountTarget: innerEl }, log, 'inner') }],
+          });
+          self.children.push(child);
+          return child;
+        },
+      }],
+    });
+    parent.render();
+    log.length = 0;
+
+    parent.render();
+
+    expect(log).toEqual(['parent:compose', 'a:kept', 'parent:hydrate', 'parent:afterRender']);
+    parent.destroy();
+  });
+
+  it('onKept() is not called when compose() is overridden without calling super, and is not replayed later', () => {
+    const log = [];
+    let skipCompose = false;
+    const parent = new LoggingParent(log, {
+      compose: (self) => { if (!skipCompose) BaseComponent.prototype.compose.call(self); },
+    });
+    parent.render();
+    parent.render();
+    expect(parent.children.map(child => child.keptCount)).toEqual([1, 1]);
+
+    skipCompose = true;
+    parent.render();
+    expect(parent.children.map(child => child.keptCount)).toEqual([1, 1]);
+
+    // compose() runs again: the still-registered children are kept, not recreated.
+    skipCompose = false;
+    parent.render();
+    expect(parent.children.length).toBe(2);
+    expect(parent.children.map(child => child.keptCount)).toEqual([2, 2]);
+    parent.destroy();
+  });
+
+  it('onKept() is skipped when compose() throws, and the next render keptCount normally', () => {
+    const log = [];
+    let fail = false;
+    const parent = new LoggingParent(log, {
+      compose: (self) => {
+        BaseComponent.prototype.compose.call(self);
+        if (fail) throw new Error('compose failed');
+      },
+    });
+    parent.render();
+
+    fail = true;
+    expect(() => parent.render()).toThrow('compose failed');
+    expect(parent.children.map(child => child.keptCount)).toEqual([0, 0]);
+
+    fail = false;
+    parent.render();
+    expect(parent.children.length).toBe(2);
+    expect(parent.children.map(child => child.keptCount)).toEqual([1, 1]);
+    expect(parent.getElement().contains(parent.children[0].getElement())).toBe(true);
+    parent.destroy();
+  });
+
+  it('onKept() can re-render the kept child itself, which stays in place', () => {
+    const log = [];
+    let text = 'first';
+    const parent = new LoggingParent(log, {
+      template: '<div data-component="a"></div>',
+      children: (self) => [{
+        selector: 'a',
+        keep: 'a',
+        factory: (el) => {
+          const child = new LoggingChild({ mountTarget: el }, log, 'a', {
+            onKept: (c) => c.render(),
+          });
+          child.generateTemplate = () => `<p>${text}</p>`;
+          self.children.push(child);
+          return child;
+        },
+      }],
+    });
+    parent.render();
+    text = 'second';
+
+    parent.render();
+
+    const [child] = parent.children;
+    expect(parent.children.length).toBe(1);
+    expect(parent.getElement().contains(child.getElement())).toBe(true);
+    expect(child.getElement().innerHTML).toBe('<p>second</p>');
+    parent.destroy();
+  });
+
+  it('onKept() re-rendering the parent is a no-op thanks to the re-entrancy guard', () => {
+    const log = [];
+    const parent = new LoggingParent(log, {
+      template: '<div data-component="a"></div>',
+      children: (self) => [{
+        selector: 'a',
+        keep: 'a',
+        factory: (el) => {
+          const child = new LoggingChild({ mountTarget: el }, log, 'a', { onKept: () => parent.render() });
+          self.children.push(child);
+          return child;
+        },
+      }],
+    });
+    parent.render();
+    log.length = 0;
+
+    parent.render();
+
+    expect(log.filter(entry => entry === 'parent:compose').length).toBe(1);
+    expect(parent.children.length).toBe(1);
+    parent.destroy();
+  });
+
+  it('onKept() sees restored focus on the detach-and-reinsert fallback path', () => {
+    let focusedWhenKept;
+    const parent = new LoggingParent([], {
+      template: '<div data-component="a"></div>',
+      children: (self) => [{
+        selector: 'a',
+        keep: 'a',
+        factory: (el) => {
+          const child = new LoggingChild({ mountTarget: el }, [], 'a', {
+            onKept: (c) => { focusedWhenKept = document.activeElement === c.getElement().querySelector('input'); },
+          });
+          self.children.push(child);
+          return child;
+        },
+      }],
+    });
+    parent.render();
+    parent.children[0].getElement().querySelector('input').focus();
+
+    parent.render();
+
+    expect(focusedWhenKept).toBe(true);
+    parent.destroy();
+  });
+
+  it('onKept() runs on the moveBefore path too, with the child already moved in place', () => {
+    Element.prototype.moveBefore = function (node, child) {
+      this.insertBefore(node, child);
+    };
+
+    try {
+      let inPlaceWhenKept;
+      const parent = new LoggingParent([], {
+        childHooks: { a: { onKept: (child) => { inPlaceWhenKept = parent.getElement().contains(child.getElement()); } } },
+      });
+      parent.render();
+
+      parent.render();
+
+      expect(parent.children.map(child => child.keptCount)).toEqual([1, 1]);
+      expect(inPlaceWhenKept).toBe(true);
+      parent.destroy();
+    } finally {
+      delete Element.prototype.moveBefore;
+    }
+  });
 });

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

@@ -1,50 +1,34 @@
-import { DomHelper } from './helpers/dom.helper.js';
-import { EventHelper } from './helpers/event.helper.js';
-import { I18nHelper } from './helpers/i18n.helper.js';
-import { PipeHelper } from './helpers/pipe.helper.js';
-import { ChildrenHelper } from './helpers/children.helper.js';
-import { CatalogHelper, CatalogConfig } from './helpers/catalog.helper.js';
-import { Component, AppEventBus } from '../../index.js';
-import { SecurityHelper, TrustLevel } from './helpers/security.helper.js';
-
-export { SecurityHelper, TrustLevel } from './helpers/security.helper.js';
-export { CatalogItemConfig, CatalogConfig, CatalogItemPrimitive } from './helpers/catalog.helper.js';
-export { TokenHelper } from './helpers/token.helper.js';
-
-/**```typescript
- * export interface ComponentConfig {
- *   selector: string;
- *   factory: (element: HTMLElement) => Component;
- * }
- * ```
- */ 
-export interface ComponentConfig {
-  selector: string;
-  factory: (element: HTMLElement) => Component;
-}
-
-export interface BaseComponentOptions {
-  template?: string;
-  mountTarget?: string | HTMLElement;
-  tagName?: keyof HTMLElementTagNameMap;
-  trustLevel?: TrustLevel;
-}
+import * as DomHelper from './helpers/dom.helper.js';
+import * as EventHelper from './helpers/event.helper.js';
+import * as I18nHelper from './helpers/i18n.helper.js';
+import * as PipeHelper from './helpers/pipe.helper.js';
+import * as ChildrenHelper from './helpers/children.helper.js';
+import type { ChildRegistry } from './helpers/children.helper.js';
+import * as PreservationHelper from './helpers/preservation.helper.js';
+import * as CatalogHelper from './helpers/catalog.helper.js';
+import { AppEventBus } from '../../services/event-bus/event-bus.js';
+import * as SecurityHelper from './helpers/security.helper.js';
+
+export * as SecurityHelper from './helpers/security.helper.js';
+export * as TokenHelper from './helpers/token.helper.js';
+export { html, raw, trustedRaw, SafeHtml } from './helpers/html.helper.js';
 
 export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
-  private _children: BaseComponent[] = [];
+  private _children: ChildRegistry = ChildrenHelper.createRegistry();
   private _isRendering = false;
   protected element: T;
   protected eventListeners: Array<[EventTarget, string, EventListener]> = [];
-  private _busSubscriptions: Array<[EventKey, (data: any) => void]> = [];
-  protected trustLevel: TrustLevel | undefined;
+  private _busSubscriptions: Array<[Nutin.EventKey, (data: any) => void]> = [];
+  protected trustLevel: Nutin.TrustLevel | undefined;
 
   constructor({
     mountTarget = '#app',
     tagName = 'div',
     trustLevel
-  }: BaseComponentOptions) {
+  }: Nutin.BaseComponentOptions) {
     this.trustLevel = trustLevel;
     this.element = DomHelper.createElement<T>(tagName, '', trustLevel);
+    DomHelper.markComponentRoot(this.element);
     DomHelper.mountElement(this.element, mountTarget);
   }
 
@@ -52,7 +36,7 @@ export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
     return this.element;
   }
 
-  public registerChildren(): ComponentConfig[] {
+  public registerChildren(): Nutin.ComponentConfig[] {
     return [];
   }
 
@@ -62,11 +46,16 @@ export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
 
     try {
       this.onBeforeRender();
-      this.element.innerHTML = SecurityHelper.sanitizeTemplate(
-        this.generateTemplate(),
-        this.trustLevel
-      );
-      this.compose();
+      const preserved = PreservationHelper.preserve(ChildrenHelper.getKeepableElements(this._children));
+      try {
+        this.element.replaceChildren(
+          SecurityHelper.sanitizeToFragment(this.generateTemplate(), this.trustLevel)
+        );
+        this.compose();
+      } finally {
+        PreservationHelper.restore(preserved);
+      }
+      this._children.kept.splice(0).forEach(child => child.onKept());
       this.hydrate();
       this.autoBindEvents()
       this.onAfterRender();
@@ -93,14 +82,16 @@ export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
   protected onAfterRender(): void {}
   protected onBeforeDestroy(): void {}
   protected onAfterDestroy(): void {}
+  // Called instead of a render when a parent re-render keeps this child as-is
+  protected onKept(): void {}
 
-  protected generateTemplate(): string {
+  protected generateTemplate(): Nutin.Template {
     return '';
   }
 
   protected hydrate(): void {
     this.parseDataAttributes();
-    DomHelper.cleanupOptionalContent();
+    DomHelper.cleanupOptionalContent(this.element);
   }
 
   protected compose(): void {
@@ -122,20 +113,20 @@ export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
     ChildrenHelper.addChildren(this, this.element, this._children);
   }
 
-  protected createCatalogComponents(config: CatalogConfig): ComponentConfig[] {
+  protected createCatalogComponents(config: Nutin.CatalogConfig): Nutin.ComponentConfig[] {
     return CatalogHelper.generateCatalog(config, this.element);
   }
 
-  protected listen<K extends EventKey>(
+  protected listen<K extends Nutin.EventKey>(
     event: K,
-    callback: (data: EventMap[K]) => void
+    callback: (data: Nutin.EventMap[K]) => void
   ): void {
     AppEventBus.subscribe(event, callback);
     this._busSubscriptions.push([event, callback]);
   }
 
-  protected listenToRenderEvents(events: EventKey[]): void {
-    events.forEach((event: EventKey) => {
+  protected listenToRenderEvents(events: Nutin.EventKey[]): void {
+    events.forEach((event: Nutin.EventKey) => {
       this.listen(event, () => this.render());
     });
   }

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

@@ -1,4 +1,4 @@
-import { CatalogHelper } from '#root/dist/src/core/base-classes/base-component/helpers/catalog.helper.js';
+import * as CatalogHelper from '#root/dist/src/core/base-classes/base-component/helpers/catalog.helper.js';
 
 describe('CatalogHelper', () => {
   let scope;
@@ -75,6 +75,7 @@ describe('CatalogHelper', () => {
         component: FakeComponent,
         props: { a: 1 },
         defaults: { b: 2 },
+        normalizeKeys: ['title'],
       },
       scope
     );
@@ -121,4 +122,38 @@ describe('CatalogHelper', () => {
     expect(calls[0]).toEqual({ value: 'red', index: 0 });
     expect(calls[1]).toEqual({ value: 'blue', index: 1 });
   });
+
+  it('without keepBy, configs carry no keep value so every item is recreated on re-render', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    const configs = CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }], selector: 'list', elementName: 'item', component: class {} },
+      scope
+    );
+    expect(configs[0].keep).toBe(undefined);
+    expect(configs[0].keepIf).toBe(undefined);
+  });
+
+  it('with keepBy, each config carries the keepBy value, a catalog-scoped identity and the raw item to compare', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    const items = [{ id: 'a' }, { id: 'b' }];
+    class FakeComponent {}
+    const configs = CatalogHelper.generateCatalog(
+      {
+        items,
+        selector: 'list',
+        elementName: 'item',
+        component: FakeComponent,
+        props: { a: 1 },
+        keepBy: (item, index) => `${item.id}-${index}`,
+      },
+      scope
+    );
+
+    expect(configs[1].selector).toBe('item-1');
+    expect(configs[1].keep).toBe('b-1');
+    expect(configs[1].scope).toBe('catalog:list:item');
+    expect(configs[1].keepIf.item).toBe(items[1]);
+    expect(configs[1].keepIf.options).toEqual({ a: 1 });
+    expect(configs[1].keepIf.component).toBe(FakeComponent);
+  });
 });