fix(ngx-dashboard): make loadDashboard() survive dashboardData re-emissions

Two mechanisms could silently revert an imperative loadDashboard() call:

1. The constructor's dashboardData effect had an #isInitialized flag that
   was set but never checked - any re-emission of the input signal (e.g.
   from toSignal() on an HTTP observable) re-ran the effect and clobbered
   prior imperative loads.

2. loadDashboard() unconditionally overwrote the store's dashboardId from
   incoming data, re-keying DashboardBridgeService and potentially
   cross-wiring sibling dashboards.

Guard the effect so it only applies the first emission, and preserve the
store's existing dashboardId on subsequent imperative loads. The
dashboardId field in DashboardDataDto is now treated as informational
metadata on re-import, matching the semantics consumers already assume.

Adds two regression tests and updates the DTO TSDoc.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: TobyBackstrom

projects/ngx-dashboard/src/lib/__tests__/dashboard-component-widget-state-integration.spec.ts

@@ -727,4 +727,97 @@ describe('DashboardComponent - Widget State Integration', () => {
       expect(menuService.lastSelectedWidgetTypeId()).toBeNull();
     });
   });
+
+  describe('loadDashboard() persistence', () => {
+    it('should preserve imperative loadDashboard() across dashboardData re-emissions', async () => {
+      // Regression: the dashboardData effect used to re-run on every input
+      // emission, silently overwriting any prior imperative loadDashboard()
+      // call. The #isInitialized guard prevents subsequent emissions from
+      // clobbering the manual load.
+      const initialData: DashboardDataDto = {
+        version: '1.1.0',
+        dashboardId: '7',
+        rows: 8,
+        columns: 16,
+        gutterSize: '0.5em',
+        cells: [],
+      };
+
+      const importedData: DashboardDataDto = {
+        version: '1.1.0',
+        dashboardId: '3',
+        rows: 7,
+        columns: 16,
+        gutterSize: '0.5em',
+        cells: [
+          {
+            row: 1,
+            col: 1,
+            rowSpan: 1,
+            colSpan: 1,
+            widgetTypeid: 'test-widget',
+            widgetState: { value: 'imported', counter: 42, modified: false },
+          },
+        ],
+      };
+
+      fixture.componentRef.setInput('dashboardData', initialData);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      // Imperative import — consumers call this after the user picks a file.
+      component.loadDashboard(importedData);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      // Simulate an upstream re-emission (e.g. a toSignal() backed by an
+      // HTTP observable producing another value after the manual load).
+      fixture.componentRef.setInput('dashboardData', { ...initialData });
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const exported = component.exportDashboard();
+      // dashboardId stays pinned to the mount-time value — the incoming
+      // id is treated as informational metadata, not an identity change.
+      expect(exported.dashboardId).toBe('7');
+      // But the imported layout and cells must win.
+      expect(exported.rows).toBe(7);
+      expect(exported.cells).toHaveSize(1);
+      expect(exported.cells[0].widgetTypeid).toBe('test-widget');
+    });
+
+    it('should preserve dashboardId across imperative loadDashboard() calls', async () => {
+      // Option C: the store's dashboardId is set once on initial mount and
+      // ignored on subsequent loadDashboard() calls. This keeps bridge
+      // registration stable when importing a file from another dashboard.
+      const initialData: DashboardDataDto = {
+        version: '1.1.0',
+        dashboardId: 'dashboard-a',
+        rows: 5,
+        columns: 5,
+        gutterSize: '1em',
+        cells: [],
+      };
+
+      fixture.componentRef.setInput('dashboardData', initialData);
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      component.loadDashboard({
+        version: '1.1.0',
+        dashboardId: 'dashboard-b',
+        rows: 4,
+        columns: 4,
+        gutterSize: '1em',
+        cells: [],
+      });
+      fixture.detectChanges();
+      await fixture.whenStable();
+
+      const exported = component.exportDashboard();
+      expect(exported.dashboardId).toBe('dashboard-a');
+      expect(exported.rows).toBe(4);
+      expect(exported.columns).toBe(4);
+    });
+  });
 });

projects/ngx-dashboard/src/lib/dashboard/dashboard.component.ts

@@ -83,10 +83,12 @@ export class DashboardComponent implements OnChanges {
       this.#bridge.unregisterDashboard(this.#store);
     });
 
-    // Initialize from dashboardData
+    // Initialize from dashboardData. Only applies the first emission so that
+    // subsequent re-emissions (e.g. from toSignal() on an HTTP observable)
+    // don't silently overwrite an imperative loadDashboard() call.
     effect(() => {
       const data = this.dashboardData();
-      if (data) {
+      if (data && !this.#isInitialized) {
         this.#store.loadDashboard(data);
         // Register with bridge service after dashboard ID is set
         this.#bridge.updateDashboardRegistration(this.#store);

projects/ngx-dashboard/src/lib/models/dashboard-data.dto.ts

@@ -8,7 +8,14 @@ export interface DashboardDataDto {
   /** Version for future compatibility and migration support */
   version: string;
 
-  /** Unique dashboard identifier managed by the client */
+  /**
+   * Unique dashboard identifier managed by the client.
+   * Set once when a dashboard is first mounted via `[dashboardData]`.
+   * On subsequent imperative `loadDashboard()` calls this field is treated
+   * as informational metadata (i.e. where the file came from) — the store's
+   * existing id is preserved so that bridge registration stays stable and
+   * Export→Import across dashboards works without rewriting the id.
+   */
   dashboardId: string;
 
   /** Grid dimensions */

projects/ngx-dashboard/src/lib/store/dashboard-store.ts

@@ -241,8 +241,14 @@ export const DashboardStore = signalStore(
         widgetsById[WidgetIdUtils.toString(widgetId)] = cell;
       });
 
+      // Adopt the incoming dashboardId only on the initial load (when the
+      // store's id is still empty). On subsequent imperative imports the
+      // existing id is preserved so that bridge registration stays stable
+      // and Export→Import across dashboards "just works" without requiring
+      // consumers to rewrite the id in the file.
+      const currentId = store.dashboardId();
       patchState(store, {
-        dashboardId: data.dashboardId,
+        ...(currentId ? {} : { dashboardId: data.dashboardId }),
         rows: data.rows,
         columns: data.columns,
         gutterSize: data.gutterSize,