@nutin/cli 2.1.1 → 3.0.0

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

@@ -1,5 +1,7 @@
-import { I18nHelper } from '#root/dist/src/core/base-classes/base-component/helpers/i18n.helper.js';
+import * as I18nHelper from '#root/dist/src/core/base-classes/base-component/helpers/i18n.helper.js';
 import { I18nService } from '#root/dist/src/core/services/index.js';
+import { CONFIG } from '#root/dist/src/core/config.js';
+import * as DomHelper from '#root/dist/src/core/base-classes/base-component/helpers/dom.helper.js';
 
 describe('I18nHelper', () => {
   let container;
@@ -9,9 +11,11 @@ describe('I18nHelper', () => {
     container = document.createElement('div');
     document.body.appendChild(container);
     originalTranslate = I18nService.translate;
+    CONFIG.i18n = true;
   });
 
   afterEach(() => {
+    CONFIG.i18n = false;
     I18nService.translate = originalTranslate;
     container.remove();
     container = null;
@@ -59,4 +63,69 @@ describe('I18nHelper', () => {
     expect(spans[0].textContent).toBe('[a]');
     expect(spans[1].textContent).toBe('[b]');
   });
+
+  it('keeps the element text, or falls back to the key, without calling I18nService when i18n is disabled', () => {
+    CONFIG.i18n = false;
+    let called = false;
+    I18nService.translate = () => { called = true; return 'translated'; };
+    container.innerHTML = '<span data-i18n="a">kept</span><span data-i18n="b"></span><input data-i18n="c">';
+
+    I18nHelper.parseI18nAttributes(container);
+
+    const spans = container.querySelectorAll('span');
+    expect(called).toBeFalsy();
+    expect(spans[0].textContent).toBe('kept');
+    expect(spans[1].textContent).toBe('b');
+    expect(container.querySelector('input').placeholder).toBe('c');
+  });
+
+  it('skips elements inside a nested component root, which translates its own content', () => {
+    I18nService.translate = (key) => `[${key}]`;
+    container.innerHTML = '<span class="own" data-i18n="a"></span><div class="child"><span class="nested" data-i18n="b">b</span></div>';
+    DomHelper.markComponentRoot(container.querySelector('.child'));
+
+    I18nHelper.parseI18nAttributes(container);
+
+    expect(container.querySelector('.own').textContent).toBe('[a]');
+    expect(container.querySelector('.nested').textContent).toBe('b');
+  });
+  it('prefixes root-relative links with the current language and a trailing slash, keeping query and hash', () => {
+    const lang = I18nService.currentLanguage;
+    container.innerHTML = '<a class="a" href="/docs"></a><a class="b" href="/"></a><a class="c" href="/docs/api?x=1#h"></a><a class="d" href="/docs/#h"></a>';
+
+    I18nHelper.parseI18nAttributes(container);
+
+    expect(container.querySelector('.a').getAttribute('href')).toBe(`/${lang}/docs/`);
+    expect(container.querySelector('.b').getAttribute('href')).toBe(`/${lang}/`);
+    expect(container.querySelector('.c').getAttribute('href')).toBe(`/${lang}/docs/api/?x=1#h`);
+    expect(container.querySelector('.d').getAttribute('href')).toBe(`/${lang}/docs/#h`);
+  });
+
+  it('leaves localized, external, protocol-relative, relative, hash, mailto and file links untouched', () => {
+    const lang = I18nService.currentLanguage;
+    const hrefs = [`/${lang}/docs`, `/${lang}`, 'https://example.com/docs', '//example.com/docs', 'docs', '#top', 'mailto:a@b.c', '/favicon.ico', '/files/guide.pdf?v=2'];
+    container.innerHTML = hrefs.map((href) => `<a href="${href}"></a>`).join('');
+
+    I18nHelper.parseI18nAttributes(container);
+
+    expect([...container.querySelectorAll('a')].map((a) => a.getAttribute('href'))).toEqual(hrefs);
+  });
+
+  it('leaves links inside a nested component root, which localizes its own', () => {
+    container.innerHTML = '<div class="child"><a href="/docs"></a></div>';
+    DomHelper.markComponentRoot(container.querySelector('.child'));
+
+    I18nHelper.parseI18nAttributes(container);
+
+    expect(container.querySelector('a').getAttribute('href')).toBe('/docs');
+  });
+
+  it('leaves links untouched when i18n is disabled', () => {
+    CONFIG.i18n = false;
+    container.innerHTML = '<a href="/docs"></a>';
+
+    I18nHelper.parseI18nAttributes(container);
+
+    expect(container.querySelector('a').getAttribute('href')).toBe('/docs');
+  });
 });

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

@@ -1,21 +1,60 @@
-import { I18nService } from '../../../index.js';
+import { I18nService } from '../../../services/i18n/i18n.js';
+import { CONFIG } from '../../../config.js';
+import * as DomHelper from './dom.helper.js';
 
-export class I18nHelper {
-  public static parseI18nAttributes(element: HTMLElement): void {
-    element.querySelectorAll('[data-i18n]').forEach(el => {
-      const key = el.getAttribute('data-i18n')!;
-      this.setTranslatedContent(el, key);
+export function parseI18nAttributes(element: HTMLElement): void {
+  element.querySelectorAll('[data-i18n]').forEach(el => {
+    // Nested components translate their own content.
+    if (DomHelper.isInsideNestedComponent(el, element)) return;
+    const key = el.getAttribute('data-i18n')!;
+    setTranslatedContent(el, key);
+  });
+  localizeLinks(element);
+}
+
+// With i18n, every page lives under a language prefix: a root-relative link ("/docs") is
+// rewritten to the page's canonical URL ("/en/docs/") so prerendered HTML and copied links
+// don't point at an unlocalized duplicate. The router strips the prefix again on navigation.
+function localizeLinks(element: HTMLElement): void {
+  if (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n) {
+    element.querySelectorAll('a[href]').forEach(el => {
+      // Nested components localize their own links.
+      if (DomHelper.isInsideNestedComponent(el, element)) return;
+      const localized = localizedHref(el.getAttribute('href')!);
+      if (localized !== null) el.setAttribute('href', localized);
     });
   }
+}
+
+// null when the href isn't an unprefixed app path: external, protocol-relative, relative,
+// a file (has an extension), or already localized.
+function localizedHref(href: string): string | null {
+  if (!href.startsWith('/') || href.startsWith('//')) return null;
+
+  const end = href.search(/[?#]/);
+  const path = end === -1 ? href : href.slice(0, end);
+  const rest = end === -1 ? '' : href.slice(end);
+  const segments = path.split('/').filter(Boolean);
+  if (segments[segments.length - 1]?.includes('.')) return null;
+  if (segments[0] && I18nService.languages.includes(segments[0] as Nutin.Language)) return null;
+
+  const suffix = segments.length ? `/${segments.join('/')}` : '';
+  return `/${I18nService.currentLanguage}${suffix}/${rest}`;
+}
+
+function setTranslatedContent(
+  el: Element, 
+  key: string
+): void {
+  // With i18n off, apply translate()'s own no-translation fallback without
+  // referencing I18nService, so prod builds can drop the service entirely.
+  const text = (globalThis.__NUTIN_I18N__ ?? CONFIG.i18n)
+    ? I18nService.translate(key, el.textContent)
+    : el.textContent || key;
 
-  private static setTranslatedContent(
-    el: Element, 
-    key: string
-  ): void {
-    if (el instanceof HTMLInputElement) {
-      el.placeholder = I18nService.translate(key, el.textContent);
-    } else {
-      el.textContent = I18nService.translate(key, el.textContent);
-    }
+  if (el instanceof HTMLInputElement) {
+    el.placeholder = text;
+  } else {
+    el.textContent = text;
   }
 }

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

@@ -1,5 +1,6 @@
-import { PipeHelper } from '#root/dist/src/core/base-classes/base-component/helpers/pipe.helper.js';
+import * as PipeHelper from '#root/dist/src/core/base-classes/base-component/helpers/pipe.helper.js';
 import { AppPipeRegistry } from '#root/dist/src/core/services/index.js';
+import * as DomHelper from '#root/dist/src/core/base-classes/base-component/helpers/dom.helper.js';
 
 describe('PipeHelper', () => {
   let container;
@@ -86,4 +87,14 @@ describe('PipeHelper', () => {
 
     warnSpy.restore();
   });
+
+  it('skips elements inside a nested component root, which pipes its own content', () => {
+    container.innerHTML = '<span class="own" data-pipe="upper">a</span><div class="child"><span class="nested" data-pipe="upper">b</span></div>';
+    DomHelper.markComponentRoot(container.querySelector('.child'));
+
+    PipeHelper.parsePipeAttributes(container);
+
+    expect(container.querySelector('.own').textContent).toBe('A');
+    expect(container.querySelector('.nested').textContent).toBe('b');
+  });
 });

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

@@ -1,47 +1,50 @@
-import { AppPipeRegistry } from '../../../index.js';
+import { AppPipeRegistry } from '../../../services/pipe-registry/pipe-registry.js';
+import * as DomHelper from './dom.helper.js';
 
-export class PipeHelper {
-  public static parsePipeAttributes(element: HTMLElement): void {
-    element.querySelectorAll('[data-pipe]').forEach(el => {
-      const pipeRaw = el.getAttribute('data-pipe');
-      if (!pipeRaw) return;
+export function parsePipeAttributes(element: HTMLElement): void {
+  element.querySelectorAll('[data-pipe]').forEach(el => {
+    // Nested components pipe their own content; piping it again here would
+    // apply every pipe twice.
+    if (DomHelper.isInsideNestedComponent(el, element)) return;
 
-      const pipes = pipeRaw.split('|').map(s => s.trim());
-      const sourceAttr = el.getAttribute('data-pipe-source');
+    const pipeRaw = el.getAttribute('data-pipe');
+    if (!pipeRaw) return;
 
-      this.processPipes(el, pipes, sourceAttr);
-    });
-  }
+    const pipes = pipeRaw.split('|').map(s => s.trim());
+    const sourceAttr = el.getAttribute('data-pipe-source');
 
-  private static processPipes(
-    el: Element, 
-    pipes: string[], 
-    sourceAttr: string | null
-  ): void {
-    let value: string;
-
-    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-      value = sourceAttr !== null ? sourceAttr : el.value;
-    } else {
-      value = sourceAttr !== null ? sourceAttr : el.textContent || '';
-    }
+    processPipes(el, pipes, sourceAttr);
+  });
+}
 
-    for (const pipe of pipes) {
-      const [pipeName, ...argParts] = pipe.split(':');
+function processPipes(
+  el: Element, 
+  pipes: string[], 
+  sourceAttr: string | null
+): void {
+  let value: string;
+
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    value = sourceAttr !== null ? sourceAttr : el.value;
+  } else {
+    value = sourceAttr !== null ? sourceAttr : el.textContent || '';
+  }
 
-      if (!pipeName) {
-        console.warn(`Empty pipe name in segment "${pipe}" - skipping.`);
-        continue;
-      }
+  for (const pipe of pipes) {
+    const [pipeName, ...argParts] = pipe.split(':');
 
-      const args = argParts.length ? argParts.join(':').split(',') : [];
-      value = AppPipeRegistry.apply(pipeName.trim(), value, args.map(a => a.trim()));
+    if (!pipeName) {
+      console.warn(`Empty pipe name in segment "${pipe}" - skipping.`);
+      continue;
     }
 
-    if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
-      el.value = value;
-    } else {
-      el.textContent = value;
-    }
+    const args = argParts.length ? argParts.join(':').split(',') : [];
+    value = AppPipeRegistry.apply(pipeName.trim(), value, args.map(a => a.trim()));
+  }
+
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+    el.value = value;
+  } else {
+    el.textContent = value;
   }
 }

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

@@ -0,0 +1,179 @@
+import * as PreservationHelper from '#root/dist/src/core/base-classes/base-component/helpers/preservation.helper.js';
+
+describe('PreservationHelper', () => {
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+    container = null;
+  });
+
+  it('restores focus and caret on an element that was detached and reattached', () => {
+    const child = document.createElement('div');
+    child.innerHTML = '<input value="hello">';
+    container.appendChild(child);
+    const input = child.querySelector('input');
+    input.focus();
+    input.setSelectionRange(1, 3);
+
+    const state = PreservationHelper.preserve([child]);
+    child.remove();
+    container.appendChild(child);
+    input.blur();
+    PreservationHelper.restore(state);
+
+    expect(document.activeElement).toBe(input);
+    expect(input.selectionStart).toBe(1);
+    expect(input.selectionEnd).toBe(3);
+  });
+
+  it('ignores focus outside the preserved elements', () => {
+    const child = document.createElement('div');
+    const outside = document.createElement('input');
+    container.append(child, outside);
+    outside.focus();
+
+    const state = PreservationHelper.preserve([child]);
+
+    expect(state.focus).toBe(null);
+  });
+
+  it('does not restore focus on an element that is no longer in the document', () => {
+    const child = document.createElement('div');
+    child.innerHTML = '<input>';
+    container.appendChild(child);
+    child.querySelector('input').focus();
+
+    const state = PreservationHelper.preserve([child]);
+    child.remove();
+    PreservationHelper.restore(state);
+
+    expect(document.activeElement).not.toBe(child.querySelector('input'));
+  });
+
+  it('does not park anything when Element.moveBefore is unavailable', () => {
+    const child = document.createElement('div');
+    container.appendChild(child);
+
+    const state = PreservationHelper.preserve([child]);
+
+    expect(state.parking).toBe(null);
+    expect(child.parentElement).toBe(container);
+  });
+
+  it('parks connected elements outside their parent with moveBefore and removes the parking spot on restore', () => {
+    Element.prototype.moveBefore = function (node, child) {
+      this.insertBefore(node, child);
+    };
+
+    try {
+      const child = document.createElement('div');
+      container.appendChild(child);
+
+      const state = PreservationHelper.preserve([child]);
+
+      expect(state.parking.contains(child)).toBe(true);
+      expect(container.contains(child)).toBe(false);
+      expect(document.body.contains(state.parking)).toBe(true);
+
+      container.appendChild(child);
+      PreservationHelper.restore(state);
+
+      expect(document.body.contains(state.parking)).toBe(false);
+    } finally {
+      delete Element.prototype.moveBefore;
+    }
+  });
+
+  it('restores the scroll position of a detached element and its descendants', () => {
+    const child = document.createElement('div');
+    child.innerHTML = '<div class="list"></div>';
+    container.appendChild(child);
+    const list = child.querySelector('.list');
+    // jsdom doesn't lay out, so scroll offsets are made writable by hand.
+    [child, list].forEach(element => {
+      Object.defineProperty(element, 'scrollTop', { value: 0, writable: true });
+      Object.defineProperty(element, 'scrollLeft', { value: 0, writable: true });
+    });
+    child.scrollLeft = 5;
+    list.scrollTop = 40;
+
+    const state = PreservationHelper.preserve([child]);
+    child.remove();
+    child.scrollLeft = 0;
+    list.scrollTop = 0;
+    container.appendChild(child);
+    PreservationHelper.restore(state);
+
+    expect(state.scroll.length).toBe(2);
+    expect(child.scrollLeft).toBe(5);
+    expect(child.scrollTop).toBe(0);
+    expect(list.scrollTop).toBe(40);
+    expect(list.scrollLeft).toBe(0);
+  });
+
+  it('does not restore the scroll position of an element that is no longer in the document', () => {
+    const child = document.createElement('div');
+    container.appendChild(child);
+    Object.defineProperty(child, 'scrollTop', { value: 30, writable: true });
+
+    const state = PreservationHelper.preserve([child]);
+    child.remove();
+    child.scrollTop = 0;
+    PreservationHelper.restore(state);
+
+    expect(child.scrollTop).toBe(0);
+  });
+
+  it('restores focus without a selection on a focused element that is not a text field', () => {
+    const child = document.createElement('div');
+    child.innerHTML = '<button>ok</button>';
+    container.appendChild(child);
+    const button = child.querySelector('button');
+    button.focus();
+
+    const state = PreservationHelper.preserve([child]);
+    child.remove();
+    container.appendChild(child);
+    PreservationHelper.restore(state);
+
+    expect(state.focus.selection).toBe(null);
+    expect(document.activeElement).toBe(button);
+  });
+
+  it('does not refocus an element that kept its focus', () => {
+    const child = document.createElement('div');
+    child.innerHTML = '<input value="hello">';
+    container.appendChild(child);
+    const input = child.querySelector('input');
+    input.focus();
+    let focusCalls = 0;
+    input.focus = () => { focusCalls++; };
+
+    const state = PreservationHelper.preserve([child]);
+    PreservationHelper.restore(state);
+
+    expect(focusCalls).toBe(0);
+  });
+
+  it('does not park anything when none of the elements are in the document', () => {
+    Element.prototype.moveBefore = function (node, child) {
+      this.insertBefore(node, child);
+    };
+
+    try {
+      const child = document.createElement('div');
+
+      const state = PreservationHelper.preserve([child]);
+
+      expect(state.parking).toBe(null);
+    } finally {
+      delete Element.prototype.moveBefore;
+    }
+  });
+});

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

@@ -0,0 +1,93 @@
+import * as DomHelper from './dom.helper.js';
+
+type SelectionDirection = 'forward' | 'backward' | 'none';
+
+interface FocusState {
+  element: HTMLElement;
+  selection: [number, number, SelectionDirection] | null;
+}
+
+interface ScrollState {
+  element: Element;
+  top: number;
+  left: number;
+}
+
+export interface PreservedState {
+  focus: FocusState | null;
+  scroll: ScrollState[];
+  parking: HTMLElement | null;
+}
+
+// Keeps reused children's DOM state across their parent's innerHTML reassignment.
+// Where Element.moveBefore() exists, children are parked outside the parent so
+// they never leave the document. Otherwise they are detached, and focus,
+// selection and scroll are restored once they're back in place.
+export function preserve(elements: HTMLElement[]): PreservedState {
+  // Parked elements keep their focus and scroll; only detached ones need restoring.
+  const parking = park(elements);
+  if (parking) return { focus: null, scroll: [], parking };
+
+  return { focus: captureFocus(elements), scroll: captureScroll(elements), parking: null };
+}
+
+export function restore(state: PreservedState): void {
+  state.parking?.remove();
+  state.scroll.forEach(({ element, top, left }) => {
+    if (!element.isConnected) return;
+    if (element.scrollTop !== top) element.scrollTop = top;
+    if (element.scrollLeft !== left) element.scrollLeft = left;
+  });
+  restoreFocus(state.focus);
+}
+
+function captureFocus(elements: HTMLElement[]): FocusState | null {
+  const active = document.activeElement;
+  if (!(active instanceof HTMLElement)) return null;
+  if (!elements.some(element => element.contains(active))) return null;
+
+  const hasSelection = (active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement)
+    && active.selectionStart !== null
+    && active.selectionEnd !== null;
+
+  return {
+    element: active,
+    selection: hasSelection
+      ? [active.selectionStart!, active.selectionEnd!, active.selectionDirection ?? 'none']
+      : null,
+  };
+}
+
+function captureScroll(elements: HTMLElement[]): ScrollState[] {
+  const scrolled: ScrollState[] = [];
+  elements.forEach(root => {
+    [root, ...Array.from(root.querySelectorAll('*'))].forEach(element => {
+      if (element.scrollTop || element.scrollLeft) {
+        scrolled.push({ element, top: element.scrollTop, left: element.scrollLeft });
+      }
+    });
+  });
+  return scrolled;
+}
+
+function park(elements: HTMLElement[]): HTMLElement | null {
+  const body = document.body;
+  const connected = elements.filter(element => element.isConnected);
+  if (!body || !connected.length || !DomHelper.canMoveBefore(body, connected[0]!)) return null;
+
+  const parking = document.createElement('div');
+  body.appendChild(parking);
+  DomHelper.prepareMoveTarget(parking, connected[0]!);
+  connected.forEach(element => DomHelper.moveBefore(parking, element, null));
+  return parking;
+}
+
+function restoreFocus(focus: FocusState | null): void {
+  if (!focus || !focus.element.isConnected) return;
+  const { element, selection } = focus;
+
+  if (document.activeElement !== element) element.focus({ preventScroll: true });
+  if (selection && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
+    element.setSelectionRange(...selection);
+  }
+}