@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/frontend/application/src/@aurora/modules/widget/archetypes/table-widget-i18n.spec.ts

@@ -0,0 +1,176 @@
+/**
+ * Tests for the Table archetype i18n header resolution (task 2.1 RED / 2.2 GREEN).
+ *
+ * Requirement: `TableColumnDef.header` is a full i18n key.
+ * The `table-widget` archetype MUST resolve it at render time and MUST
+ * re-resolve on language change. A test that passes when headers are
+ * rendered literally would be tautological — these tests fail on literal rendering.
+ *
+ * Coverage:
+ *   A. Header key renders its translation, NOT the raw key string.
+ *   B. Multiple columns each render their own translated header.
+ *   C. A language change causes headers to re-render in the new language.
+ *
+ * Translation data is provided as a flat map that mirrors how TranslocoService
+ * stores scope translations after `transloco.load('o-auth/en')` merges them:
+ * key `access-token.RowId` becomes `o-auth.access-token.RowId` in the store.
+ *
+ * IMPORTANT: `availableLangs` MUST be set in `translocoConfig`.
+ * Without it, TranslocoService treats 'en' as a scope (not a lang), prepends
+ * it to every key, and all lookups fail — producing 'en.o-auth.…' as the
+ * missing-key fallback. This is a Transloco testing gotcha.
+ */
+import '@angular/compiler';
+import { TestBed } from '@angular/core/testing';
+import { TranslocoService, TranslocoTestingModule } from '@jsverse/transloco';
+import { of } from 'rxjs';
+import type { WidgetDataSource } from '../widget-data-source';
+import { TableWidgetComponent } from './table-widget.component';
+
+// ── Translation fixtures (flat keys as stored internally by TranslocoService) ──
+
+const EN_TRANSLATIONS = {
+  'o-auth.access-token.RowId': 'Row ID',
+  'o-auth.access-token.IsRevoked': 'Revoked',
+  'o-auth.access-token.ExpiresAt': 'Expires At',
+};
+
+const ES_TRANSLATIONS = {
+  'o-auth.access-token.RowId': 'ID de fila',
+  'o-auth.access-token.IsRevoked': 'Revocado',
+  'o-auth.access-token.ExpiresAt': 'Caduca el',
+};
+
+/** Shared Transloco testing setup. `availableLangs` prevents 'en' from being
+ *  treated as a scope (which would prefix all keys with 'en.' and break lookups). */
+const TRANSLOCO_TESTING = TranslocoTestingModule.forRoot({
+  langs: { en: EN_TRANSLATIONS, es: ES_TRANSLATIONS },
+  translocoConfig: {
+    defaultLang: 'en',
+    availableLangs: ['en', 'es'],
+  },
+});
+
+// ── Data helpers ──────────────────────────────────────────────────────────────
+
+const ROWS: Record<string, unknown>[] = [
+  { rowId: 'abc123', isRevoked: false, expiresAt: '2025-01-01' },
+];
+
+const I18N_COLUMNS = [
+  { key: 'rowId', header: 'o-auth.access-token.RowId' },
+  { key: 'isRevoked', header: 'o-auth.access-token.IsRevoked' },
+  { key: 'expiresAt', header: 'o-auth.access-token.ExpiresAt' },
+];
+
+// ── A. Header key renders translation, NOT the raw key ────────────────────────
+
+describe('TableWidgetComponent — header i18n: key renders translated text', () => {
+  it('renders the English translation of the header key, not the literal key string', () => {
+    const source: WidgetDataSource<Record<string, unknown>[]> = {
+      kind: 'observable',
+      connect: () => of(ROWS),
+    };
+
+    TestBed.configureTestingModule({
+      imports: [TableWidgetComponent, TRANSLOCO_TESTING],
+    });
+
+    const fixture = TestBed.createComponent(TableWidgetComponent);
+    TestBed.runInInjectionContext(() => {
+      fixture.componentRef.setInput('source', source);
+      fixture.componentRef.setInput('columns', I18N_COLUMNS);
+    });
+    fixture.detectChanges();
+
+    const el: HTMLElement = fixture.nativeElement;
+    const headers = Array.from(el.querySelectorAll('th')).map((th) => th.textContent?.trim());
+
+    // If headers are rendered literally, this would contain 'o-auth.access-token.RowId' → FAILS.
+    expect(headers).toContain('Row ID');
+    expect(headers).toContain('Revoked');
+    expect(headers).toContain('Expires At');
+
+    // The raw key string must NOT appear as a visible header.
+    expect(headers).not.toContain('o-auth.access-token.RowId');
+    expect(headers).not.toContain('o-auth.access-token.IsRevoked');
+    expect(headers).not.toContain('o-auth.access-token.ExpiresAt');
+  });
+});
+
+// ── B. Multiple columns each render their own translation ─────────────────────
+
+describe('TableWidgetComponent — header i18n: all columns translated', () => {
+  it('each column header key independently resolves to its translated text', () => {
+    const source: WidgetDataSource<Record<string, unknown>[]> = {
+      kind: 'observable',
+      connect: () => of(ROWS),
+    };
+
+    TestBed.configureTestingModule({
+      imports: [TableWidgetComponent, TRANSLOCO_TESTING],
+    });
+
+    const fixture = TestBed.createComponent(TableWidgetComponent);
+    TestBed.runInInjectionContext(() => {
+      fixture.componentRef.setInput('source', source);
+      fixture.componentRef.setInput('columns', I18N_COLUMNS);
+    });
+    fixture.detectChanges();
+
+    const el: HTMLElement = fixture.nativeElement;
+    const headers = Array.from(el.querySelectorAll('th')).map((th) => th.textContent?.trim());
+
+    expect(headers).toHaveLength(3);
+    expect(headers[0]).toBe('Row ID');
+    expect(headers[1]).toBe('Revoked');
+    expect(headers[2]).toBe('Expires At');
+  });
+});
+
+// ── C. Language change re-renders headers in the new language ─────────────────
+
+describe('TableWidgetComponent — header i18n: language change re-renders headers', () => {
+  // Restore 'en' after this suite so the active-lang singleton cannot leak into
+  // other spec files that share a Vitest worker (FIX B — cross-file isolation).
+  afterEach(() => {
+    TestBed.inject(TranslocoService).setActiveLang('en');
+  });
+
+  it('re-renders headers in Spanish after switching language from English', () => {
+    const source: WidgetDataSource<Record<string, unknown>[]> = {
+      kind: 'observable',
+      connect: () => of(ROWS),
+    };
+
+    TestBed.configureTestingModule({
+      imports: [TableWidgetComponent, TRANSLOCO_TESTING],
+    });
+
+    const fixture = TestBed.createComponent(TableWidgetComponent);
+    const transloco = TestBed.inject(TranslocoService);
+
+    TestBed.runInInjectionContext(() => {
+      fixture.componentRef.setInput('source', source);
+      fixture.componentRef.setInput('columns', I18N_COLUMNS);
+    });
+    fixture.detectChanges();
+
+    // Confirm English renders first
+    const el: HTMLElement = fixture.nativeElement;
+    let headers = Array.from(el.querySelectorAll('th')).map((th) => th.textContent?.trim());
+    expect(headers[0]).toBe('Row ID');
+
+    // Switch to Spanish — TranslocoService emits selectTranslation(), which bumps
+    // _langTick, which Angular re-evaluates in the next CD cycle.
+    transloco.setActiveLang('es');
+    fixture.detectChanges();
+
+    headers = Array.from(el.querySelectorAll('th')).map((th) => th.textContent?.trim());
+
+    // If re-rendering on language change is NOT implemented, headers still show English → FAILS.
+    expect(headers[0]).toBe('ID de fila');
+    expect(headers[1]).toBe('Revocado');
+    expect(headers[2]).toBe('Caduca el');
+  });
+});

package/dist/templates/frontend/application/src/@aurora/modules/widget/archetypes/table-widget.component.ts

@@ -0,0 +1,230 @@
+import {
+  Component,
+  computed,
+  DestroyRef,
+  inject,
+  Injector,
+  input,
+  OnInit,
+  runInInjectionContext,
+  signal,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { TranslocoService } from '@jsverse/transloco';
+import { merge } from 'rxjs';
+import type { RefreshableWidget } from '../refreshable-widget';
+import type { WidgetDataSource } from '../widget-data-source';
+import { runWidgetDataSource, type WidgetDataSourceState } from '../widget-data-source-runner';
+import { deriveScopes } from '../widget-scope-deriver';
+
+// ─── TableColumnDef ───────────────────────────────────────────────────────────
+
+export interface TableColumnDef {
+  /** Property path used to read each row's cell value (e.g. `'name'`, `'status'`). */
+  key: string;
+  /**
+   * Full i18n key for the column header (e.g. `'o-auth.access-token.Token'`).
+   * The `table-widget` archetype resolves this key reactively at render time via
+   * `TranslocoService` — the header always reflects the active language.
+   * Must be a full key (scope included as the first dot-segment). Never pass a
+   * literal display string; a leftover literal renders as an untranslated key.
+   */
+  header: string;
+}
+
+// ─── TableWidgetComponent ─────────────────────────────────────────────────────
+
+/**
+ * Archetype component for read-only top-N table widgets.
+ *
+ * Renders a plain HTML table showing up to `maxRows` rows from the data
+ * source. No sort controls, filter inputs, pagination, or row-detail
+ * affordances — this is intentionally a preview surface. The drill-down
+ * link (full list) is rendered by the tile chrome via `AuroraWidgetDef.link`.
+ *
+ * Implements `RefreshableWidget` to support the tile chrome's refresh button.
+ *
+ * Column `header` values are treated as full Transloco i18n keys and resolved
+ * reactively on every language change via `TranslocoService.selectTranslation`.
+ * No scope is registered here — the dashboard page loads BC scopes on demand
+ * (D3). The headers re-evaluate whenever `_langTick` changes.
+ */
+@Component({
+  selector: 'aurora-table-widget',
+  // h-full makes the host fill the tile's content area so the inner scroll wrapper
+  // below has a bounded height (same h-full chain the chart widget relies on). Without
+  // it the wrapper sizes to content and never scrolls, breaking the sticky header.
+  host: { class: 'block h-full' },
+  template: `
+    @if (loading()) {
+      <div class="animate-pulse space-y-1">
+        @for (_ of skeletonRows; track $index) {
+          <div class="bg-muted h-6 w-full rounded"></div>
+        }
+      </div>
+    } @else if (error()) {
+      <div
+        data-testid="error-state"
+        aria-live="polite"
+        role="alert"
+        class="text-destructive flex items-center gap-2 text-sm"
+      >
+        <span aria-hidden="true">⚠</span>
+        <span>Failed to load widget data.</span>
+      </div>
+    } @else {
+      <!-- The table owns its scroll container (both axes), bounded to h-full. The
+           header sticks to THIS container's top edge — which has no padding — so rows
+           can never bleed above it. The tile's own p-2 stays OUTSIDE this box, just
+           framing the table and clipping any overflow. -->
+      <div class="h-full overflow-auto">
+        <table class="w-full text-sm">
+          <thead>
+            <tr>
+              @for (col of columns(); track col.key) {
+                <!-- sticky top-0 pins the header flush to the scroll container's top
+                     while rows scroll under it; bg-card makes it opaque so rows don't
+                     show through; z-10 keeps it above the body cells. -->
+                <th
+                  class="text-muted-foreground bg-card sticky top-0 z-10 border-b px-2 py-1 text-left font-medium"
+                >
+                  {{ translateHeader(col.header) }}
+                </th>
+              }
+            </tr>
+          </thead>
+          <tbody>
+            @for (row of rows(); track $index) {
+              <tr class="border-b last:border-0">
+                @for (col of columns(); track col.key) {
+                  <td class="px-2 py-1">{{ cellDisplay(row[col.key]) }}</td>
+                }
+              </tr>
+            }
+            @if (rows().length === 0) {
+              <tr>
+                <td
+                  class="text-muted-foreground px-2 py-4 text-center"
+                  [attr.colspan]="columns().length"
+                >
+                  —
+                </td>
+              </tr>
+            }
+          </tbody>
+        </table>
+      </div>
+    }
+  `,
+})
+export class TableWidgetComponent implements OnInit, RefreshableWidget {
+  // ─── Inputs ──────────────────────────────────────────────────────────────
+
+  readonly source = input.required<WidgetDataSource<Record<string, unknown>[]>>();
+  readonly columns = input.required<TableColumnDef[]>();
+  readonly maxRows = input<number>(5);
+
+  // ─── Private ─────────────────────────────────────────────────────────────
+
+  private readonly _injector = inject(Injector);
+  private readonly _destroyRef = inject(DestroyRef);
+  private readonly _transloco = inject(TranslocoService);
+  private readonly _state = signal<WidgetDataSourceState<Record<string, unknown>[]> | null>(null);
+
+  /**
+   * Incremented each time a new language's translations become available.
+   * Reading it in `translateHeader` makes the template re-evaluate headers
+   * whenever the language changes (RULE 3: use selectTranslation, not langChanges$).
+   */
+  private readonly _langTick = signal(0);
+
+  /** Skeleton placeholder rows shown during loading. */
+  readonly skeletonRows = Array.from({ length: 5 });
+
+  // ─── Derived signals ─────────────────────────────────────────────────────
+
+  readonly loading = computed(() => this._state()?.loading() ?? true);
+  readonly error = computed(() => this._state()?.error() ?? null);
+
+  /** The top-N slice of the data source's current value. */
+  readonly rows = computed(() => (this._state()?.value() ?? []).slice(0, this.maxRows()));
+
+  // ─── Lifecycle ───────────────────────────────────────────────────────────
+
+  ngOnInit(): void {
+    this._run();
+    this._subscribeToLangChanges();
+  }
+
+  // ─── RefreshableWidget ───────────────────────────────────────────────────
+
+  refresh(): void {
+    this._run();
+  }
+
+  // ─── Template helpers ─────────────────────────────────────────────────────
+
+  /**
+   * Resolves a full i18n key to its translated text in the active language.
+   * Reads `_langTick()` so Angular re-evaluates this call whenever the language
+   * changes and new translations are available.
+   * Falls back to the raw key string when the key is not found (prevents blank headers).
+   */
+  translateHeader(key: string): string {
+    // Reading _langTick() establishes a reactive dependency so the template
+    // re-evaluates this call after each language change.
+    this._langTick();
+    return this._transloco.translate(key);
+  }
+
+  /**
+   * Formats a raw cell value for display in the table (W6c fix).
+   * Converts booleans to Yes/No, null/undefined to '—', objects to their JSON
+   * representation, and everything else to its string form.
+   */
+  cellDisplay(value: unknown): string {
+    if (value === null || value === undefined) return '—';
+    if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+    if (typeof value === 'object') return JSON.stringify(value);
+    return String(value);
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────
+
+  private _run(): void {
+    runInInjectionContext(this._injector, () => {
+      this._state()?.unsubscribe();
+      this._state.set(runWidgetDataSource(this.source()));
+    });
+  }
+
+  /**
+   * Subscribes to translation-ready events. Merges the global `selectTranslation()`
+   * stream with a `selectTranslation(scope)` stream per BC scope the column headers
+   * belong to (derived from the header keys via `deriveScopes`).
+   *
+   * The global stream fires on every lang change (after base translations load),
+   * which is correct when no BC scope is in play. The per-scope streams fire when
+   * the BC scope file for the new language is loaded — making the archetype more
+   * targeted to its own scope while still working when only the global scope changes.
+   *
+   * Uses `selectTranslation` (not bare `langChanges$`) so we react only AFTER the
+   * new-language JSON is fully loaded (RULE 3). Bumps `_langTick` so
+   * `translateHeader()` re-runs in the template.
+   */
+  private _subscribeToLangChanges(): void {
+    const headerKeys = this.columns().map((col) => col.header);
+    const bcScopes = deriveScopes(headerKeys);
+
+    const streams = [
+      this._transloco.selectTranslation(),
+      ...bcScopes.map((scope) => this._transloco.selectTranslation(scope)),
+    ];
+
+    merge(...streams)
+      .pipe(takeUntilDestroyed(this._destroyRef))
+      .subscribe(() => {
+        this._langTick.update((tick) => tick + 1);
+      });
+  }
+}