@matter-server/dashboard 0.3.4 → 0.3.5

package/src/pages/network/base-network-graph.ts

@@ -23,6 +23,9 @@ export abstract class BaseNetworkGraph extends LitElement {
     @state()
     protected _selectedNodeId: number | string | null = null;
 
+    @state()
+    protected _physicsEnabled = true;
+
     protected _network?: Network;
     protected _nodesDataSet?: DataSet<NetworkGraphNode>;
     protected _edgesDataSet?: DataSet<NetworkGraphEdge>;
@@ -30,6 +33,11 @@ export abstract class BaseNetworkGraph extends LitElement {
     protected _resizeObserver?: ResizeObserver;
     protected _themeUnsubscribe?: () => void;
     protected _updateDebounceTimer?: ReturnType<typeof setTimeout>;
+    protected _autoFreezeTimer?: ReturnType<typeof setTimeout>;
+    /** Whether auto-freeze has already been applied (to avoid re-freezing after user unfreezes) */
+    private _autoFreezeApplied = false;
+    /** Whether initial fit has been done (to preserve user's zoom/pan after first load) */
+    private _initialFitDone = false;
 
     /** Store original edge colors for restoration after highlighting */
     private _originalEdgeColors: Map<string, { color: string; highlight: string }> = new Map();
@@ -166,6 +174,7 @@ export abstract class BaseNetworkGraph extends LitElement {
         super.disconnectedCallback();
         this._resizeObserver?.disconnect();
         this._themeUnsubscribe?.();
+        this._cancelAutoFreezeTimer();
         if (this._updateDebounceTimer) {
             clearTimeout(this._updateDebounceTimer);
         }
@@ -243,25 +252,21 @@ export abstract class BaseNetworkGraph extends LitElement {
             this._dispatchNodeSelected(null);
         });
 
-        // Auto-fit after stabilization completes
+        // Auto-fit after initial stabilization completes (only once)
         this._network.on("stabilizationIterationsDone", () => {
-            // Fit with padding to keep nodes away from edges
-            this._network?.fit({
-                animation: {
-                    duration: 500,
-                    easingFunction: "easeInOutQuad",
-                },
-            });
-        });
+            if (!this._initialFitDone) {
+                // Fit with padding to keep nodes away from edges
+                this._network?.fit({
+                    animation: {
+                        duration: 500,
+                        easingFunction: "easeInOutQuad",
+                    },
+                });
+                this._initialFitDone = true;
 
-        // Also fit when physics fully stops (catches any drift after initial stabilization)
-        this._network.on("stabilized", () => {
-            this._network?.fit({
-                animation: {
-                    duration: 300,
-                    easingFunction: "easeInOutQuad",
-                },
-            });
+                // Start auto-freeze timer (5 seconds after initial stabilization)
+                this._startAutoFreezeTimer();
+            }
         });
 
         this._updateGraph();
@@ -286,6 +291,99 @@ export abstract class BaseNetworkGraph extends LitElement {
         });
     }
 
+    /**
+     * Zooms in by 20%.
+     */
+    public zoomIn(): void {
+        if (!this._network) return;
+        const scale = this._network.getScale();
+        this._network.moveTo({
+            scale: scale * 1.2,
+            animation: {
+                duration: 200,
+                easingFunction: "easeInOutQuad",
+            },
+        });
+    }
+
+    /**
+     * Zooms out by 20%.
+     */
+    public zoomOut(): void {
+        if (!this._network) return;
+        const scale = this._network.getScale();
+        this._network.moveTo({
+            scale: scale / 1.2,
+            animation: {
+                duration: 200,
+                easingFunction: "easeInOutQuad",
+            },
+        });
+    }
+
+    /**
+     * Returns whether physics simulation is currently enabled.
+     */
+    public get physicsEnabled(): boolean {
+        return this._physicsEnabled;
+    }
+
+    /**
+     * Enables or disables physics simulation (node movement/settling).
+     * When disabled, nodes freeze in place; when enabled, they resume settling.
+     * @param enabled Whether to enable physics
+     * @param isManual If true, cancels any pending auto-freeze (user manually toggled)
+     */
+    public setPhysicsEnabled(enabled: boolean, isManual = true): void {
+        // If user manually toggles, cancel auto-freeze to respect their choice
+        if (isManual) {
+            this._cancelAutoFreezeTimer();
+            this._autoFreezeApplied = true; // Prevent future auto-freeze
+        }
+
+        this._physicsEnabled = enabled;
+        this._network?.setOptions({
+            physics: { enabled },
+        });
+    }
+
+    /**
+     * Starts the auto-freeze timer. Physics will be disabled after 5 seconds
+     * unless the user manually toggles physics or the timer is cancelled.
+     */
+    private _startAutoFreezeTimer(): void {
+        // Don't auto-freeze if already applied or user has manually controlled physics
+        if (this._autoFreezeApplied) {
+            return;
+        }
+
+        this._cancelAutoFreezeTimer();
+        this._autoFreezeTimer = setTimeout(() => {
+            if (!this._autoFreezeApplied && this._physicsEnabled) {
+                this.setPhysicsEnabled(false, false); // false = not manual, don't mark as applied
+                this._autoFreezeApplied = true;
+                // Dispatch event so parent can update UI state
+                this.dispatchEvent(
+                    new CustomEvent("physics-changed", {
+                        detail: { enabled: false },
+                        bubbles: true,
+                        composed: true,
+                    }),
+                );
+            }
+        }, 5000);
+    }
+
+    /**
+     * Cancels any pending auto-freeze timer.
+     */
+    private _cancelAutoFreezeTimer(): void {
+        if (this._autoFreezeTimer) {
+            clearTimeout(this._autoFreezeTimer);
+            this._autoFreezeTimer = undefined;
+        }
+    }
+
     /**
      * Selects a node by ID and focuses on it.
      */
@@ -323,16 +421,20 @@ export abstract class BaseNetworkGraph extends LitElement {
     protected _highlightConnections(nodeId: number | string): void {
         if (!this._edgesDataSet || !this._nodesDataSet) return;
 
-        // Store original colors before highlighting
         const allEdges = this._edgesDataSet.get();
+
+        // First pass: Store original colors ONLY if not already stored.
+        // We must do this BEFORE any highlighting modifies edge colors.
+        // If edges were already highlighted (switching between nodes), the colors
+        // in the DataSet might be dimmed, so we rely on previously stored values.
         for (const edge of allEdges) {
             const edgeId = String(edge.id);
             if (!this._originalEdgeColors.has(edgeId)) {
-                const colorObj = edge.color as { color: string; highlight: string };
-                this._originalEdgeColors.set(edgeId, {
-                    color: colorObj?.color ?? "#999999",
-                    highlight: colorObj?.highlight ?? "#999999",
-                });
+                const colorObj = edge.color as { color: string; highlight: string } | undefined;
+                // Extract colors, with fallbacks
+                const color = colorObj?.color ?? "#999999";
+                const highlight = colorObj?.highlight ?? color;
+                this._originalEdgeColors.set(edgeId, { color, highlight });
             }
         }
 
@@ -351,21 +453,19 @@ export abstract class BaseNetworkGraph extends LitElement {
             }
         }
 
-        // Update edges - make connected ones thicker
+        // Update edges - make connected ones thicker, dim non-connected ones
         const dimmedColor = this._getDimmedEdgeColor();
         const edgeUpdates = allEdges.map((edge: NetworkGraphEdge) => {
             const isConnected = edge.from === nodeId || edge.to === nodeId;
             const originalColor = this._originalEdgeColors.get(String(edge.id));
+            // Use stored original color for connected edges, fallback to a default if somehow missing
+            const connectedColor = originalColor ?? { color: "#999999", highlight: "#999999" };
             return {
                 id: edge.id,
                 width: isConnected ? 3 : 1,
-                // Dim non-connected edges
                 color: isConnected
-                    ? { color: originalColor?.color, highlight: originalColor?.highlight }
-                    : {
-                          color: dimmedColor,
-                          highlight: dimmedColor,
-                      },
+                    ? { color: connectedColor.color, highlight: connectedColor.highlight }
+                    : { color: dimmedColor, highlight: dimmedColor },
             };
         });
         this._edgesDataSet.update(edgeUpdates);

package/src/util/matter-status.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Matter.js Status codes mapped to readable names.
+ * @see MatterSpecification.v142.Core § 8.10.1
+ */
+export const MatterStatusNames: Record<number, string> = {
+    0: "Success",
+    1: "Failure",
+    125: "InvalidSubscription",
+    126: "UnsupportedAccess",
+    127: "UnsupportedEndpoint",
+    128: "InvalidAction",
+    129: "UnsupportedCommand",
+    133: "InvalidCommand",
+    134: "UnsupportedAttribute",
+    135: "ConstraintError",
+    136: "UnsupportedWrite",
+    137: "ResourceExhausted",
+    139: "NotFound",
+    140: "UnreportableAttribute",
+    141: "InvalidDataType",
+    143: "UnsupportedRead",
+    146: "DataVersionMismatch",
+    148: "Timeout",
+    155: "UnsupportedNode",
+    156: "Busy",
+    157: "AccessRestricted",
+    195: "UnsupportedCluster",
+    197: "NoUpstreamSubscription",
+    198: "NeedsTimedInteraction",
+    199: "UnsupportedEvent",
+    200: "PathsExhausted",
+    201: "TimedRequestMismatch",
+    202: "FailsafeRequired",
+    203: "InvalidInState",
+    204: "NoCommandResponse",
+    205: "TermsAndConditionsChanged",
+    206: "MaintenanceRequired",
+    207: "DynamicConstraintError",
+    208: "AlreadyExists",
+    209: "InvalidTransportType",
+};
+
+/** Get readable name for a Matter status code */
+export function getMatterStatusName(status: number): string {
+    return MatterStatusNames[status] ?? `Unknown(${status})`;
+}
+
+/** Result type for Matter operations with status details */
+export interface MatterOperationResult {
+    success: boolean;
+    status: number;
+    statusName: string;
+}
+
+/** Outcome type for batch operations */
+export type BatchOutcome = "all_success" | "all_failed" | "partial";
+
+/** Result type for batch Matter operations (multiple entries) */
+export interface MatterBatchResult {
+    /** Overall outcome: all succeeded, all failed, or partial */
+    outcome: BatchOutcome;
+    /** Number of successful operations (status === 0) */
+    successCount: number;
+    /** Number of failed operations (status !== 0) */
+    failureCount: number;
+    /** Count of failures per status code, e.g. { 126: 2, 135: 1 } */
+    errorCounts: Record<number, number>;
+    /** Human-readable summary message for display */
+    message: string;
+}
+
+/** Create a successful operation result */
+export function successResult(): MatterOperationResult {
+    return { success: true, status: 0, statusName: "Success" };
+}
+
+/** Create a failed operation result from a status code */
+export function failureResult(status: number): MatterOperationResult {
+    return { success: false, status, statusName: getMatterStatusName(status) };
+}
+
+/** Create an operation result from a status code (success if 0) */
+export function resultFromStatus(status: number): MatterOperationResult {
+    const statusName = getMatterStatusName(status);
+    return { success: status === 0, status, statusName };
+}
+
+/**
+ * Analyze multiple operation results and produce a batch result summary.
+ * @param results Array of objects with a `status` property (0 = success).
+ *                If null, undefined, or empty, this is treated as a failed/unknown batch.
+ * @returns MatterBatchResult with outcome, counts, and human-readable message
+ */
+export function analyzeBatchResults(results: Array<{ status: number }> | null | undefined): MatterBatchResult {
+    if (!results || results.length === 0) {
+        return {
+            outcome: "all_failed",
+            successCount: 0,
+            failureCount: 0,
+            errorCounts: {},
+            message: "No response/results returned",
+        };
+    }
+
+    let successCount = 0;
+    let failureCount = 0;
+    const errorCounts: Record<number, number> = {};
+
+    for (const result of results) {
+        if (result.status === 0) {
+            successCount++;
+        } else {
+            failureCount++;
+            errorCounts[result.status] = (errorCounts[result.status] ?? 0) + 1;
+        }
+    }
+
+    let outcome: BatchOutcome;
+    if (failureCount === 0) {
+        outcome = "all_success";
+    } else if (successCount === 0) {
+        outcome = "all_failed";
+    } else {
+        outcome = "partial";
+    }
+
+    const message = formatBatchMessage(outcome, successCount, failureCount, errorCounts);
+
+    return { outcome, successCount, failureCount, errorCounts, message };
+}
+
+/** Format a human-readable message for batch results */
+function formatBatchMessage(
+    outcome: BatchOutcome,
+    successCount: number,
+    failureCount: number,
+    errorCounts: Record<number, number>,
+): string {
+    const entryWord = (count: number) => (count === 1 ? "entry" : "entries");
+
+    if (outcome === "all_success") {
+        return "Write successful";
+    }
+
+    // Format error breakdown: "2x UnsupportedAccess (126), 1x ConstraintError (135)"
+    const errorParts = Object.entries(errorCounts)
+        .map(([code, count]) => {
+            const statusCode = parseInt(code, 10);
+            return `${count}x ${getMatterStatusName(statusCode)} (${code})`;
+        })
+        .join(", ");
+
+    if (outcome === "all_failed") {
+        return `All ${failureCount} ${entryWord(failureCount)} failed: ${errorParts}`;
+    }
+
+    // partial
+    return `Partial failure: ${successCount} ${entryWord(successCount)} succeeded, ${failureCount} failed (${errorParts}). Please verify.`;
+}