@nutin/cli 2.1.1 → 3.0.0

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

@@ -1,13 +1,9 @@
-import { BaseComponent, BaseComponentOptions } from '../../index.js';
-
-export interface ViewOptions extends BaseComponentOptions {
-  viewName: string;
-}
+import { BaseComponent } from '../base-component/base-component.js';
 
 export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComponent<T> {
   private _viewName: string;
   protected routeParams: Record<string, string> = {};
-  private _template: string;
+  private _template: Nutin.Template;
 
   constructor({
     template,
@@ -15,7 +11,7 @@ export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComp
     mountTarget = '#app',
     viewName,
     trustLevel,
-  }: ViewOptions) {
+  }: Nutin.ViewOptions) {
     super({ mountTarget, tagName, trustLevel });
     if (!viewName) throw new Error('View requires a viewName.');
     this._template = template ?? '';
@@ -26,7 +22,7 @@ export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComp
     return this._viewName;
   }
 
-  protected override generateTemplate(): string {
+  protected override generateTemplate(): Nutin.Template {
     return this._template;
   }
 
@@ -46,6 +42,13 @@ export abstract class View<T extends HTMLElement = HTMLElement> extends BaseComp
     return key in this.routeParams && this.routeParams[key] !== undefined;
   }
 
+  // The page's title, read by the router after each navigation (document.title). Override it
+  // for a title that depends on the route, e.g. the page being shown. Undefined: the router
+  // uses config/seo.json's title, then the "<viewName>.title" translation, then viewName.
+  public documentTitle(): string | undefined {
+    return undefined;
+  }
+
   // Navigation hooks — called by router only, never by render lifecycle
   public onEnter(): void {}
   public onExit(): void {}

package/templates/base/src/core/index.ts.hbs

@@ -1,5 +1,7 @@
-// Abstract classes
+// Abstract classes and helpers:
+// Component, View, Service
 export * from './base-classes/index.js';
 
-// Core functionalities
+// Core functionalities:
+// EventBus and facades, global components, httpClient, i18n, pipeRegistry, router 
 export * from './services/index.js';

package/templates/base/src/core/internals.d.ts.hbs

@@ -1,27 +1,206 @@
-declare interface NavigationEventMap {
-  'navigate': { path: string };
-  'reload': {};
-}
+// Nutin's public types, all inside the global `Nutin` namespace so they can't collide with other packages' globals.
+// No import needed: the app extends it in src/app/globals.d.ts.
+// This file must stay free of top-level import/export, so runtime classes go through import().
+declare namespace Nutin {
+  interface RouterEventMap {
+    'navigate': { path: string };
+    'reload': undefined;
+  }
 
-declare interface LifecycleEventMap {
-  'before-render': {};
-  'after-render': {};
-  'before-destroy': {};
-  'after-destroy': {};
-  'view-mount': { viewName: string };
-  'view-unmount': { viewName: string };
-}
+  interface LifecycleEventMap {
+    'before-render': undefined;
+    'after-render': undefined;
+    'before-destroy': undefined;
+    'after-destroy': undefined;
+    'view-mount': { viewName: string };
+    'view-unmount': { viewName: string };
+  }
+
+  interface I18nEventMap {
+    'language-changed': {
+      lang: string;
+    };
+  }
+
+  interface FrameworkEventMap extends RouterEventMap, LifecycleEventMap, I18nEventMap {}
+
+  interface AppEventMap {}
+
+  interface EventMap extends FrameworkEventMap, AppEventMap {}
 
-declare interface I18nEventMap {
-  'language-changed': {
-    lang: string;
+  type EventKey = keyof EventMap;
+
+  type Subscription<K extends EventKey = EventKey> = {
+    event: K;
+    callback: (data: EventMap[K]) => void;
+    once?: boolean;
   };
-}
 
-declare interface FrameworkEventMap extends NavigationEventMap, LifecycleEventMap, I18nEventMap {}
+  // Components
+
+  type Template = string | import('./index.js').SafeHtml;
+
+  type TrustLevel = 'strict' | 'normal' | 'trusted';
+
+  interface ComponentConfig {
+    selector: string;
+    factory: (element: HTMLElement) => import('./index.js').Component;
+    // Same keep value on the next render: the child is kept as-is instead of recreated
+    keep?: string | number;
+  }
+
+  interface BaseComponentOptions {
+    template?: Template;
+    mountTarget?: string | HTMLElement;
+    tagName?: keyof HTMLElementTagNameMap;
+    trustLevel?: TrustLevel;
+  }
+
+  interface ComponentProps {
+    // Common HTML attributes - extend as needed
+    className?: string;
+    style?: string;
+    textContent?: string;
+
+    // Form field bindings - extend as needed
+    name?: string;
+    email?: string;
+
+    // Allow for additional data-bind attributes
+    [key: string]: any;
+  }
+
+  interface ComponentOptions<K = any> extends BaseComponentOptions {
+    props?: ComponentProps;
+    config?: K;
+    defaults?: Partial<K>;
+    templateFn?: (config?: K) => Template;
+    normalizeKeys?: (keyof K)[];
+  }
+
+  interface ViewOptions extends BaseComponentOptions {
+    viewName: string;
+  }
+
+  interface CatalogConfig extends ComponentOptions {
+    items: CatalogItemConfig[];
+    elementName: string;
+    elementTag?: keyof HTMLElementTagNameMap;
+    selector: string;
+    component: new (el: HTMLElement, data: any, props?: any) => import('./index.js').Component;
+    // Same value on the next render keeps an unchanged item as-is; changed items are recreated
+    keepBy?: (item: any, index: number) => string | number;
+  }
+
+  interface CatalogItemBase {
+    index: number;
+  }
+
+  type CatalogItemObject<T extends object> = T & CatalogItemBase;
+
+  interface CatalogItemPrimitive extends CatalogItemBase {
+    value: string | number | boolean | null | undefined;
+  }
 
-declare interface AppEventMap {}
+  type CatalogItemConfig<T = any> =
+    T extends object ? CatalogItemObject<T> : CatalogItemPrimitive;
 
-declare interface EventMap extends FrameworkEventMap, AppEventMap {}
+  // Router
+
+  /**
+   * Route guard function that receives route parameters and returns:
+   * - true to allow navigation
+   * - false to block it
+   * - string to redirect to a different route
+   */
+  type RouteGuard = (params: Record<string, string>) => boolean | string | Promise<boolean | string>;
+
+  /**
+   * Creates a route's view. Returning a Promise makes the route lazy: e.g.
+   * `() => import('./views/about/about.view.js').then((m) => new m.AboutView())`
+   * puts the view's code in its own chunk, loaded on the first visit.
+   */
+  type ViewFactory = () => import('./index.js').View | Promise<import('./index.js').View>;
+
+  /**
+   * Route configuration - can be just a view factory or an object with guards
+   */
+  type RouteConfig = ViewFactory | {
+    view: ViewFactory;
+    guards?: RouteGuard[];
+  };
+
+  type Routes = Record<string, RouteConfig>;
+
+  interface RouteMatch {
+    route: RouteConfig;
+    params: Record<string, string>;
+    pattern: string;
+  }
+
+  // Instance types of the framework services
+  type Router = ReturnType<typeof import('./index.js').AppRouter>;
+  type EventBus = InstanceType<typeof import('./index.js').EventBus>;
+  type HttpClient = InstanceType<typeof import('./index.js').HttpClient>;
+
+  // HTTP
+
+  type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+  type QueryValue = string | number | boolean | null | undefined;
+
+  /**
+   * headers?: Record<string, string>;
+   * queryParams?: Record<string, QueryValue | QueryValue[]>;
+   * timeout?: number;
+   * signal?: AbortSignal;
+   * credentials? / cache? / referrerPolicy? / redirect?: passed to fetch as-is.
+   */
+  interface RequestConfig {
+    headers?: Record<string, string>;
+    queryParams?: Record<string, QueryValue | QueryValue[]>;
+    timeout?: number;
+    signal?: AbortSignal;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    referrerPolicy?: ReferrerPolicy;
+    redirect?: RequestRedirect;
+  }
+
+  interface HttpClientOptions {
+    // URL prefixes (origin + path) whose paths may contain encoded "/" or "\" (%2F, %5C).
+    trustedAPIs?: string[];
+  }
+
+  // i18n & pipes
+
+  type Language = typeof import('./services/i18n/languages.js').LANGUAGES[number];
+  type Translations = Record<string, any>;
+
+  type PipeFunction = (value: any, ...args: any[]) => string;
+
+  // Globals
+
+  interface GlobalMountable {
+    render(): HTMLElement;
+    destroy?(): void;
+  }
+
+  interface GlobalConfig<T extends GlobalMountable = GlobalMountable> {
+    /** The component's own class — constructed internally as `new component(mountTarget)`. */
+    component: new (mountTarget: HTMLElement) => T;
+    /** Stamped onto the mounted root element; pass this same id to `hideGlobals`/`revealGlobals`. */
+    id: string;
+  }
+
+  interface RegisterGlobalsOptions {
+    /** Rendered and prepended to `<body>`, in the given order (e.g. a header). */
+    before?: GlobalConfig[];
+    /** Rendered and appended to `<body>`, in the given order (e.g. a footer). */
+    after?: GlobalConfig[];
+  }
+}
 
-declare type EventKey = keyof EventMap;
+// Set by the builder's esbuild `define` so prod bundles can drop i18n code when it's
+// disabled; undefined in tests and tsc output, which fall back to CONFIG.i18n.
+declare var __NUTIN_I18N__: boolean | undefined;

package/templates/base/src/core/services/event-bus/event-bus.test.js.hbs

@@ -175,6 +175,24 @@ describe('EventBus', () => {
     expect(regularCalls).toBe(2);
   });
 
+  it('keeps dispatching to the other listeners when one throws, and still removes a throwing once() handler', () => {
+    const errSpy = spyOn(console, 'error');
+    errSpy.andCallFake(() => {});
+    let received = 0;
+    let onceCalls = 0;
+
+    eventBus.once('notification', () => { onceCalls++; throw new Error('boom'); });
+    eventBus.subscribe('notification', () => { received++; });
+
+    eventBus.emit('notification', {});
+    eventBus.emit('notification', {});
+
+    expect(onceCalls).toBe(1);
+    expect(received).toBe(2);
+    expect(errSpy.callCount).toBe(1);
+    errSpy.restore();
+  });
+
   it('off(event) with no callback removes every handler for that event', () => {
     let callsA = 0;
     let callsB = 0;

package/templates/base/src/core/services/event-bus/event-bus.ts.hbs

@@ -1,15 +1,10 @@
-import { Service } from "../../index.js";
+import { Service } from "../../base-classes/service/service.js";
 
-export type IEventBus = InstanceType<typeof EventBus>;
-
-export type Subscription<K extends EventKey = EventKey> = {
-  event: K;
-  callback: (data: EventMap[K]) => void;
-  once?: boolean;
-};
+// The payload is required unless the event declares none (`undefined` in its EventMap entry).
+type EventArgs<K extends Nutin.EventKey> = undefined extends Nutin.EventMap[K] ? [data?: Nutin.EventMap[K]] : [data: Nutin.EventMap[K]];
 
 export class EventBus extends Service<EventBus> {
-  private _subscriptions: Subscription[] = [];
+  private _subscriptions: Nutin.Subscription[] = [];
 
   constructor() {
     super();
@@ -17,29 +12,35 @@ export class EventBus extends Service<EventBus> {
   }
 
   private handlers: {
-    [K in EventKey]?: Array<(data: EventMap[K]) => void>;
+    [K in Nutin.EventKey]?: Array<(data: Nutin.EventMap[K]) => void>;
   } = {};
 
-  public subscribe<K extends EventKey>(
+  public subscribe<K extends Nutin.EventKey>(
     event: K,
-    callback: (data: EventMap[K]) => void
+    callback: (data: Nutin.EventMap[K]) => void
   ): void {
     this.addHandler(event, callback, false);
   }
 
-  public once<K extends EventKey>(
+  public once<K extends Nutin.EventKey>(
     event: K,
-    callback: (data: EventMap[K]) => void
+    callback: (data: Nutin.EventMap[K]) => void
   ): void {
     this.addHandler(event, callback, true);
   }
 
-  public emit<K extends EventKey>(event: K, data?: EventMap[K]): void {
+  public emit<K extends Nutin.EventKey>(event: K, ...[data]: EventArgs<K>): void {
     const callbacks = this.handlers[event];
     if (!callbacks) return;
 
     callbacks.slice().forEach(callback => {
-      callback(data!);
+      // A failing listener is reported but doesn't keep the others (the router's
+      // included) from receiving the event.
+      try {
+        callback(data as Nutin.EventMap[K]);
+      } catch (error) {
+        console.error(`Error in a "${event}" listener:`, error);
+      }
 
       const subIndex = this._subscriptions.findIndex(
         sub => sub.event === event && sub.callback === callback && sub.once
@@ -50,17 +51,17 @@ export class EventBus extends Service<EventBus> {
     });
   }
 
-  public off<K extends EventKey>(
+  public off<K extends Nutin.EventKey>(
     event: K,
-    callback?: (data: EventMap[K]) => void
+    callback?: (data: Nutin.EventMap[K]) => void
   ): void {
     const handlers = this.handlers[event];
     if (!handlers) return;
 
     if (callback) {
       (this.handlers as Record<
-        EventKey,
-        Array<(data: EventMap[K]) => void>
+        Nutin.EventKey,
+        Array<(data: Nutin.EventMap[K]) => void>
       >)[event] = handlers.filter(h => h !== callback);
     } else {
       delete this.handlers[event];
@@ -71,18 +72,18 @@ export class EventBus extends Service<EventBus> {
     );
   }
 
-  private addHandler<K extends EventKey>(
+  private addHandler<K extends Nutin.EventKey>(
     event: K,
-    callback: (data: EventMap[K]) => void,
+    callback: (data: Nutin.EventMap[K]) => void,
     once: boolean
   ): void {
     if (!this.handlers[event]) {
       this.handlers[event] = [];
     }
     (
-      this.handlers as Record<EventKey, Array<(data: EventMap[K]) => void>>
+      this.handlers as Record<Nutin.EventKey, Array<(data: Nutin.EventMap[K]) => void>>
     )[event].push(callback);
-    this._subscriptions.push({ event, callback, once } as Subscription);
+    this._subscriptions.push({ event, callback, once } as Nutin.Subscription);
   }
 
   private cleanupEventListeners = (): void => {
@@ -93,4 +94,4 @@ export class EventBus extends Service<EventBus> {
   };
 }
 
-export const AppEventBus = EventBus.getInstance();
+export const AppEventBus = /* @__PURE__ */ EventBus.getInstance();

package/templates/base/src/core/services/event-bus/lifecycle.facade.ts.hbs

@@ -1,7 +1,7 @@
-import { AppEventBus, IEventBus } from "./event-bus.js";
+import { AppEventBus } from "./event-bus.js";
 
 class LifecycleFacade {
-  constructor(private bus: IEventBus) {}
+  constructor(private bus: Nutin.EventBus) {}
 
   beforeRender(): void {
     this.bus.emit('before-render');
@@ -58,4 +58,4 @@ class LifecycleFacade {
   }
 }
 
-export const Lifecycle = new LifecycleFacade(AppEventBus);
+export const Lifecycle = /* @__PURE__ */ new LifecycleFacade(AppEventBus);

package/templates/base/src/core/services/event-bus/navigation.facade.ts.hbs

@@ -1,7 +1,7 @@
-import { AppEventBus, IEventBus } from "./event-bus.js";
+import { AppEventBus } from "./event-bus.js";
 
 class NavigationFacade {
-  constructor(private bus: IEventBus) {}
+  constructor(private bus: Nutin.EventBus) {}
 
   navigateTo(path: string): void {
     this.bus.emit('navigate', { path });
@@ -22,4 +22,4 @@ class NavigationFacade {
   }
 }
 
-export const Navigation = new NavigationFacade(AppEventBus);
+export const Navigation = /* @__PURE__ */ new NavigationFacade(AppEventBus);

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

@@ -1,41 +1,17 @@
-import { Service } from '../../base-classes/index.js';
-
-export interface GlobalMountable {
-  render(): HTMLElement;
-  destroy?(): void;
-}
-
-export interface GlobalConfig<T extends GlobalMountable = GlobalMountable> {
-  /** The component's own class — constructed internally as `new component(mountTarget)`. */
-  component: new (mountTarget: HTMLElement) => T;
-  /** Stamped onto the mounted root element; pass this same id to `hideGlobals`/`revealGlobals`. */
-  id: string;
-}
-
-export interface RegisterGlobalsOptions {
-  /** Rendered and prepended to `<body>`, in the given order (e.g. a header). */
-  before?: GlobalConfig[];
-  /** Rendered and appended to `<body>`, in the given order (e.g. a footer). */
-  after?: GlobalConfig[];
-}
+import { Service } from '../../base-classes/service/service.js';
 
 export class Globals extends Service<Globals> {
-  private _mounted: Record<string, GlobalMountable> = {};
+  private _mounted: Record<string, Nutin.GlobalMountable> = {};
   private _originalDisplay: Record<string, string> = {};
 
   constructor() { super(); }
 
-  public register({ before = [], after = [] }: RegisterGlobalsOptions): void {
-    // Component subclasses generated via `nutin generate component` type their
-    // mountTarget param as HTMLElement, but DomHelper.mountElement only
-    // *appends* (rather than replacing) the target when mountTarget is a string
-    // selector. This cast satisfies the stricter constructor type while still
-    // passing the string 'body' through at runtime, so components append into
-    // <body> instead of replacing it.
+  public register({ before = [], after = [] }: Nutin.RegisterGlobalsOptions): void {
+    // Satisfies the stricter constructor type while letting components append into <body> instead of replacing it.
     const mountTarget = 'body' as unknown as HTMLElement;
     const isElement = (el: HTMLElement | null): el is HTMLElement => el !== null;
 
-    const mount = ({ component: Component, id }: GlobalConfig): HTMLElement | null => {
+    const mount = ({ component: Component, id }: Nutin.GlobalConfig): HTMLElement | null => {
       if (this._mounted[id]) {
         console.warn(`Global "${id}" is already registered - skipping.`);
         return null;
@@ -80,13 +56,12 @@ export class Globals extends Service<Globals> {
 /**
  * Mounts components outside the router's render target (`<main id="app">`),
  * e.g. a header/footer that should persist across every route. Each entry's
- * `component` is constructed internally — callers never see or handle
- * `mountTarget` themselves — and its rendered root element is given the
+ * `component` is constructed internally and its rendered root element is given the
  * entry's `id`, so `hideGlobals(ids)`/`revealGlobals(ids)` can target it
  * later by that same id. Registering an `id` that's already registered logs
  * a `console.warn` and skips it.
  */
-export const registerGlobals = (options: RegisterGlobalsOptions): void => {
+export const registerGlobals = (options: Nutin.RegisterGlobalsOptions): void => {
   Globals.getInstance().register(options);
 };