@nutin/cli 1.3.0 → 2.0.0

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

@@ -0,0 +1,158 @@
+import { BaseComponent, AppEventBus } from '#root/dist/src/core/index.js';
+
+class TestComponent extends BaseComponent {
+  constructor(options = {}, hooks = {}) {
+    super(options);
+    this.hooks = hooks;
+    this.calls = [];
+  }
+  generateTemplate() {
+    this.calls.push('generateTemplate');
+    return this.hooks.template ?? '';
+  }
+  onBeforeRender() {
+    this.calls.push('onBeforeRender');
+    this.hooks.onBeforeRender?.(this);
+  }
+  onAfterRender() {
+    this.calls.push('onAfterRender');
+  }
+  onBeforeDestroy() {
+    this.calls.push('onBeforeDestroy');
+  }
+  onAfterDestroy() {
+    this.calls.push('onAfterDestroy');
+  }
+  compose() {
+    this.calls.push('compose');
+    super.compose();
+  }
+  hydrate() {
+    this.calls.push('hydrate');
+    super.hydrate();
+  }
+  autoBindEvents() {
+    this.calls.push('autoBindEvents');
+    super.autoBindEvents();
+  }
+}
+
+describe('BaseComponent', () => {
+  let app;
+
+  beforeEach(() => {
+    // dist/src/index.html already ships a real <main id="app">, so reuse it
+    // instead of appending a second element with the same id.
+    app = document.getElementById('app');
+  });
+
+  afterEach(() => {
+    AppEventBus.cleanupEventListeners();
+    app.innerHTML = '';
+    app = null;
+  });
+
+  it('mounts its element into the default "#app" target on construction', () => {
+    const component = new TestComponent();
+    expect(app.contains(component.getElement())).toBe(true);
+  });
+
+  it('creates the element with the given tagName', () => {
+    const component = new TestComponent({ tagName: 'section' });
+    expect(component.getElement().tagName).toBe('SECTION');
+  });
+
+  it('defaults registerChildren() to an empty array', () => {
+    const component = new TestComponent();
+    expect(component.registerChildren()).toEqual([]);
+  });
+
+  it('render() runs the full pipeline in order', () => {
+    const component = new TestComponent({}, { template: '<span>hi</span>' });
+    component.render();
+    expect(component.calls).toEqual([
+      'onBeforeRender',
+      'generateTemplate',
+      'compose',
+      'hydrate',
+      'autoBindEvents',
+      'onAfterRender',
+    ]);
+    expect(component.getElement().innerHTML).toBe('<span>hi</span>');
+  });
+
+  it('render() sanitizes the generated template before inserting it', () => {
+    const component = new TestComponent({}, { template: '<p>hi</p><script>bad()</script>' });
+    component.render();
+    expect(component.getElement().innerHTML).toBe('<p>hi</p>');
+  });
+
+  it('render() guards against re-entrant rendering and returns the existing element', () => {
+    let innerResult;
+    const component = new TestComponent({}, {
+      onBeforeRender: (self) => {
+        innerResult = self.render();
+      },
+    });
+
+    const outerResult = component.render();
+
+    expect(innerResult).toBe(outerResult);
+    expect(component.calls.filter(c => c === 'compose').length).toBe(1);
+    expect(component.calls.filter(c => c === 'onBeforeRender').length).toBe(1);
+  });
+
+  it('destroy() runs onBeforeDestroy then onAfterDestroy and removes the element from the DOM', () => {
+    const component = new TestComponent();
+    component.render();
+    const el = component.getElement();
+    const callsBeforeDestroy = component.calls.length;
+
+    component.destroy();
+
+    const destroyCalls = component.calls.slice(callsBeforeDestroy);
+    expect(destroyCalls).toEqual(['onBeforeDestroy', 'onAfterDestroy']);
+    expect(app.contains(el)).toBe(false);
+  });
+
+  it('listen() subscribes via AppEventBus and stops receiving events after destroy()', () => {
+    const component = new TestComponent();
+    let received = null;
+    component.listen('user-login', (data) => { received = data; });
+
+    AppEventBus.emit('user-login', { id: 1 });
+    expect(received).toEqual({ id: 1 });
+
+    component.destroy();
+    received = null;
+    AppEventBus.emit('user-login', { id: 2 });
+    expect(received).toBe(null);
+  });
+
+  it('listenToRenderEvents() triggers render() whenever one of the given events fires', () => {
+    const component = new TestComponent();
+    component.listenToRenderEvents(['user-login']);
+
+    const before = component.calls.filter(c => c === 'onBeforeRender').length;
+    AppEventBus.emit('user-login', {});
+    const after = component.calls.filter(c => c === 'onBeforeRender').length;
+
+    expect(after).toBe(before + 1);
+    component.destroy();
+  });
+
+  it('createCatalogComponents() delegates to CatalogHelper.generateCatalog scoped to the component element', () => {
+    const component = new TestComponent();
+    component.getElement().innerHTML = '<div data-catalog="list"></div>';
+
+    const configs = component.createCatalogComponents({
+      items: [{ id: 1 }],
+      selector: 'list',
+      elementName: 'item',
+      component: class {},
+    });
+
+    expect(configs.length).toBe(1);
+    component.destroy();
+  });
+});

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

@@ -1,24 +1,26 @@
 import { DomHelper } from './helpers/dom.helper.js';
 import { EventHelper } from './helpers/event.helper.js';
-{{#if i18n}}
 import { I18nHelper } from './helpers/i18n.helper.js';
-{{/if}}
 import { PipeHelper } from './helpers/pipe.helper.js';
 import { ChildrenHelper } from './helpers/children.helper.js';
 import { CatalogHelper, CatalogConfig } from './helpers/catalog.helper.js';
-import { TrustLevel } from './helpers/security.helper.js';
-export { CatalogItemConfig } 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) => BaseComponent;
+ *   factory: (element: HTMLElement) => Component;
  * }
  * ```
  */ 
 export interface ComponentConfig {
   selector: string;
-  factory: (element: HTMLElement) => BaseComponent;
+  factory: (element: HTMLElement) => Component;
 }
 
 export interface BaseComponentOptions {
@@ -30,63 +32,111 @@ export interface BaseComponentOptions {
 
 export abstract class BaseComponent<T extends HTMLElement = HTMLElement> {
   private _children: BaseComponent[] = [];
+  private _isRendering = false;
   protected element: T;
-  protected eventListeners: Array<[string, EventListener]> = [];
+  protected eventListeners: Array<[EventTarget, string, EventListener]> = [];
+  private _busSubscriptions: Array<[EventKey, (data: any) => void]> = [];
+  protected trustLevel: TrustLevel | undefined;
 
   constructor({
-    template = '',
     mountTarget = '#app',
     tagName = 'div',
     trustLevel
   }: BaseComponentOptions) {
-    this.element = DomHelper.createElement<T>(tagName, template, trustLevel);
-    this.parseDataAttributes();
-    this.autoBindEvents();
+    this.trustLevel = trustLevel;
+    this.element = DomHelper.createElement<T>(tagName, '', trustLevel);
     DomHelper.mountElement(this.element, mountTarget);
   }
 
-  public childConfigs(): ComponentConfig[] {
+  public getElement(): T {
+    return this.element;
+  }
+
+  public registerChildren(): ComponentConfig[] {
     return [];
   }
 
+  public render(): HTMLElement {
+    if (this._isRendering) return this.element;
+    this._isRendering = true;
+
+    try {
+      this.onBeforeRender();
+      this.element.innerHTML = SecurityHelper.sanitizeTemplate(
+        this.generateTemplate(),
+        this.trustLevel
+      );
+      this.compose();
+      this.hydrate();
+      this.autoBindEvents()
+      this.onAfterRender();
+      return this.element;
+    } finally {
+      this._isRendering = false;
+    }
+  }
+
   public destroy(): void {
-    EventHelper.destroyEvents(this.element, this.eventListeners);
+    this.onBeforeDestroy();
+    EventHelper.destroyEvents(this.eventListeners);
+    this._busSubscriptions.forEach(([event, callback]) => {
+      AppEventBus.off(event, callback);
+    });
+    this._busSubscriptions = [];
     ChildrenHelper.destroyChildren(this._children);
     this.element.remove();
+    this.onAfterDestroy();
   }
 
-  public render(): HTMLElement {
-    this.addChildren();
-    return this.element;
+  // Lifecycle hooks — override in subclasses as needed
+  protected onBeforeRender(): void {}
+  protected onAfterRender(): void {}
+  protected onBeforeDestroy(): void {}
+  protected onAfterDestroy(): void {}
+
+  protected generateTemplate(): string {
+    return '';
   }
 
-/**
- * ```typescript
-interface CatalogConfig {
-  array: CatalogItemConfig[];
-  elementName: string;
-  elementTag?: keyof HTMLElementTagNameMap;
-  selector: string;
-  component: new (el: HTMLElement, data: any) => BaseComponent;
-};
-  ```
-*/
-  protected catalogConfig(config: CatalogConfig): ComponentConfig[] {
-    return CatalogHelper.generateCatalog(config);
+  protected hydrate(): void {
+    this.parseDataAttributes();
+    DomHelper.cleanupOptionalContent();
+  }
+
+  protected compose(): void {
+    this.addChildren();
   }
 
   protected parseDataAttributes(): void {
-    {{#if i18n}}
     I18nHelper.parseI18nAttributes(this.element);
-    {{/if}}
     PipeHelper.parsePipeAttributes(this.element);
   }
 
   protected autoBindEvents(): void {
+    EventHelper.destroyEvents(this.eventListeners);
+    this.eventListeners.length = 0;
     EventHelper.bindEvents(this, this.element, this.eventListeners);
   }
 
   protected addChildren(): void {
     ChildrenHelper.addChildren(this, this.element, this._children);
   }
+
+  protected createCatalogComponents(config: CatalogConfig): ComponentConfig[] {
+    return CatalogHelper.generateCatalog(config, this.element);
+  }
+
+  protected listen<K extends EventKey>(
+    event: K,
+    callback: (data: EventMap[K]) => void
+  ): void {
+    AppEventBus.subscribe(event, callback);
+    this._busSubscriptions.push([event, callback]);
+  }
+
+  protected listenToRenderEvents(events: EventKey[]): void {
+    events.forEach((event: EventKey) => {
+      this.listen(event, () => this.render());
+    });
+  }
 }

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

@@ -0,0 +1,124 @@
+import { CatalogHelper } from '#root/dist/src/core/base-classes/base-component/helpers/catalog.helper.js';
+
+describe('CatalogHelper', () => {
+  let scope;
+
+  beforeEach(() => {
+    scope = document.createElement('div');
+    document.body.appendChild(scope);
+  });
+
+  afterEach(() => {
+    scope.remove();
+    scope = null;
+  });
+
+  it('returns an empty array when config.items is missing or empty', () => {
+    expect(CatalogHelper.generateCatalog({ items: [], selector: 'x', elementName: 'item' }, scope)).toEqual([]);
+    expect(CatalogHelper.generateCatalog({ selector: 'x', elementName: 'item' }, scope)).toEqual([]);
+  });
+
+  it('returns an empty array when no matching [data-catalog] container exists', () => {
+    const configs = CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }], selector: 'missing', elementName: 'item' },
+      scope
+    );
+    expect(configs).toEqual([]);
+  });
+
+  it('builds a wrapper + inner [data-component] element per array item inside each matching container', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }, { id: 2 }], selector: 'list', elementName: 'item', component: class {} },
+      scope
+    );
+
+    const container = scope.querySelector('[data-catalog="list"]');
+    expect(container.children.length).toBe(2);
+    expect(container.children[0].dataset.index).toBe('0');
+    expect(container.children[0].querySelector('[data-component="item-0"]')).toBeDefined();
+    expect(container.children[1].dataset.index).toBe('1');
+    expect(container.children[1].querySelector('[data-component="item-1"]')).toBeDefined();
+  });
+
+  it('clears any pre-existing content in the container before building', () => {
+    scope.innerHTML = '<div data-catalog="list"><span class="stale"></span></div>';
+    CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }], selector: 'list', elementName: 'item', component: class {} },
+      scope
+    );
+    expect(scope.querySelector('.stale')).toBe(null);
+  });
+
+  it('uses the configured elementTag for the wrapper element', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }], selector: 'list', elementName: 'item', elementTag: 'li', component: class {} },
+      scope
+    );
+    const wrapper = scope.querySelector('[data-catalog="list"]').firstElementChild;
+    expect(wrapper.tagName).toBe('LI');
+  });
+
+  it('returns component configs whose factory constructs the configured component with merged options and an indexed item', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    const calls = [];
+    class FakeComponent {
+      constructor(el, data, props) { calls.push({ el, data, props }); }
+    }
+
+    const configs = CatalogHelper.generateCatalog(
+      {
+        items: [{ id: 1 }],
+        selector: 'list',
+        elementName: 'item',
+        component: FakeComponent,
+        props: { a: 1 },
+        defaults: { b: 2 },
+      },
+      scope
+    );
+
+    expect(configs.length).toBe(1);
+    expect(configs[0].selector).toBe('item-0');
+
+    const el = scope.querySelector('[data-component="item-0"]');
+    configs[0].factory(el);
+
+    expect(calls[0].el).toBe(el);
+    expect(calls[0].data).toEqual({ id: 1, index: 0 });
+    expect(calls[0].props).toEqual({ a: 1, b: 2 });
+  });
+
+  it('skips falsy or non-HTMLElement entries returned by querySelectorAll', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    const realContainer = scope.querySelector('[data-catalog="list"]');
+    const fakeScope = { querySelectorAll: () => [null, realContainer] };
+
+    const configs = CatalogHelper.generateCatalog(
+      { items: [{ id: 1 }], selector: 'list', elementName: 'item', component: class {} },
+      fakeScope
+    );
+
+    expect(configs.length).toBe(1);
+  });
+
+  it('wraps primitive array items as { value, index }', () => {
+    scope.innerHTML = '<div data-catalog="list"></div>';
+    const calls = [];
+    class FakeComponent {
+      constructor(_el, data) { calls.push(data); }
+    }
+
+    const configs = CatalogHelper.generateCatalog(
+      { items: ['red', 'blue'], selector: 'list', elementName: 'item', component: FakeComponent },
+      scope
+    );
+
+    configs[0].factory(scope.querySelector('[data-component="item-0"]'));
+    configs[1].factory(scope.querySelector('[data-component="item-1"]'));
+
+    expect(calls[0]).toEqual({ value: 'red', index: 0 });
+    expect(calls[1]).toEqual({ value: 'blue', index: 1 });
+  });
+});

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

@@ -1,11 +1,11 @@
-import { BaseComponent, ComponentConfig } from "../base-component.js";
+import { Component, ComponentConfig, ComponentOptions } from "../../index.js";
 
-export interface CatalogConfig {
-  array: CatalogItemConfig[];
+export interface CatalogConfig extends ComponentOptions {
+  items: CatalogItemConfig[];
   elementName: string;
   elementTag?: keyof HTMLElementTagNameMap;
   selector: string;
-  component: new (el: HTMLElement, data: any) => BaseComponent;
+  component: new (el: HTMLElement, data: any, props?: any) => Component;
 };
 
 export interface CatalogItemBase {
@@ -23,12 +23,12 @@ export type CatalogItemConfig<T = any> =
 
 /**
  * ```typescript
-interface CatalogConfig {
-  array: CatalogItemConfig[];
+interface CatalogConfig extends ComponentOptions {
+  items: CatalogItemConfig[];
   elementName: string;
   elementTag?: keyof HTMLElementTagNameMap;
   selector: string;
-  component: new (el: HTMLElement, data: any) => BaseComponent;
+  component: new (el: HTMLElement, data: any) => Component;
 };
 
 type CatalogItemConfig<T = any> =
@@ -36,42 +36,57 @@ type CatalogItemConfig<T = any> =
   ```
 */
 export class CatalogHelper {
-  public static generateCatalog(config: CatalogConfig): ComponentConfig[] {
-    if (!config.array || config.array.length < 1) return [];
+  public static generateCatalog(config: CatalogConfig, scope: Element = document.documentElement): ComponentConfig[] {
+    if (!config.items || config.items.length < 1) return [];
 
-    const container = document.querySelector(`[data-catalog="${config.selector}"]`);
+    const componentConfigs: ComponentConfig[] = [];
+    const containers = scope.querySelectorAll(`[data-catalog="${config.selector}"]`);
 
-    if (!container || !(container instanceof HTMLElement)) return [];
+    containers.forEach((container) => {
+      if (!container || !(container instanceof HTMLElement)) return;
+      componentConfigs.push(...this.getComponentConfigItems(config, container))
+    })
 
-    const componentConfigs: ComponentConfig[] = [];
+    return componentConfigs;
+  }
 
-    for (let i = 0; i < config.array.length; i++) { 
+  private static getComponentConfigItems(config: CatalogConfig, container: HTMLElement): ComponentConfig[] {
+    container.innerHTML = '';
+    const componentConfigs: ComponentConfig[] = [];
+    for (let i = 0; i < config.items.length; i++) {
       this.createElements(i, config, container);
       this.pushConfig(i, componentConfigs, config);
     }
-
     return componentConfigs;
   }
 
   private static createElements(index: number, config: CatalogConfig, container: HTMLElement): void {
-    const el = document.createElement(config.elementTag || 'div');
+    const wrapper = document.createElement(config.elementTag || 'div');
+    const el = document.createElement('div');
+    wrapper.appendChild(el);
     el.setAttribute('data-component', `${config.elementName}-${index}`);
-    el.dataset.index = String(index);
-    container?.appendChild(el);
+    wrapper.dataset.index = String(index);
+    container?.appendChild(wrapper);
   }
 
   private static pushConfig(index: number, componentConfigs: ComponentConfig[], config: CatalogConfig): void {
-    const item = config.array[index];
+    const configWithIndex = this.getConfigWithIndex(config, index)
+
+    const { props, defaults, normalizeKeys } = config;
+    const options = { ...props, ...defaults, ...normalizeKeys };
 
-    const configWithIndex: CatalogItemConfig = (item && typeof item === 'object')
-      ? { ...(item as object), index: index }
-      : { value: item, index: index };
-    
     componentConfigs.push(
       { 
         selector: `${config.elementName}-${index}`,
-        factory: (el) => new config.component(el, configWithIndex)
+        factory: (el) => new config.component(el, configWithIndex, options),
       },
     )
   }
+
+  private static getConfigWithIndex(config: CatalogConfig, index: number): CatalogItemConfig {
+    const item = config.items[index];
+    return (item && typeof item === 'object')
+      ? { ...(item as object), index: index }
+      : { value: item, index: index };    
+  }
 }

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

@@ -0,0 +1,74 @@
+import { ChildrenHelper } from '#root/dist/src/core/base-classes/base-component/helpers/children.helper.js';
+
+describe('ChildrenHelper', () => {
+  let element;
+
+  beforeEach(() => {
+    element = document.createElement('div');
+    document.body.appendChild(element);
+  });
+
+  afterEach(() => {
+    element.remove();
+    element = null;
+  });
+
+  it('instantiates, renders and registers a child component for each matching [data-component] element', () => {
+    element.innerHTML = '<div data-component="widget"></div>';
+    const rendered = [];
+    const factoryCalls = [];
+
+    const component = {
+      registerChildren: () => [{
+        selector: 'widget',
+        factory: (el) => {
+          factoryCalls.push(el);
+          return {
+            render: () => rendered.push('rendered'),
+            destroy: () => {},
+          };
+        },
+      }],
+    };
+
+    const children = [];
+    ChildrenHelper.addChildren(component, element, children);
+
+    expect(factoryCalls.length).toBe(1);
+    expect(factoryCalls[0]).toBe(element.querySelector('[data-component="widget"]'));
+    expect(rendered.length).toBe(1);
+    expect(children.length).toBe(1);
+  });
+
+  it('instantiates one child per matched element for a single registerChildren entry', () => {
+    element.innerHTML = '<div data-component="widget"></div><div data-component="widget"></div>';
+    const component = {
+      registerChildren: () => [{
+        selector: 'widget',
+        factory: () => ({ render: () => {}, destroy: () => {} }),
+      }],
+    };
+
+    const children = [];
+    ChildrenHelper.addChildren(component, element, children);
+
+    expect(children.length).toBe(2);
+  });
+
+  it('does nothing when there are no registerChildren', () => {
+    const component = { registerChildren: () => [] };
+    const children = [];
+    ChildrenHelper.addChildren(component, element, children);
+    expect(children.length).toBe(0);
+  });
+
+  it('destroyChildren calls destroy on every child', () => {
+    let destroyCount = 0;
+    const children = [
+      { destroy: () => destroyCount++ },
+      { destroy: () => destroyCount++ },
+    ];
+    ChildrenHelper.destroyChildren(children);
+    expect(destroyCount).toBe(2);
+  });
+});

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

@@ -6,7 +6,7 @@ export class ChildrenHelper {
     element: HTMLElement, 
     children: BaseComponent[]
   ): void {
-    const configs: ComponentConfig[] = component.childConfigs();
+    const configs: ComponentConfig[] = component.registerChildren();
     configs.forEach(config => {
       element.querySelectorAll(`[data-component="${config.selector}"]`).forEach(el => {
         if (el instanceof HTMLElement) {