feat: add port label visibility control based on zoom level and settings

Author: trkbt10

src/components/canvas/CanvasBase.tsx

@@ -4,6 +4,7 @@
 import * as React from "react";
 import { useNodeCanvas } from "../../contexts/composed/canvas/viewport/context";
 import { useEditorActionState } from "../../contexts/composed/EditorActionStateContext";
+import { useNodeEditor } from "../../contexts/composed/node-editor/context";
 import { applyZoomDelta } from "../../utils/zoomUtils";
 import { SelectionBox } from "./SelectionBox";
 import styles from "./CanvasBase.module.css";
@@ -40,6 +41,7 @@ const hasNodePayload = (event: React.DragEvent): boolean => {
 export const CanvasBase: React.FC<CanvasBaseProps> = ({ children, className, showGrid, onNodeDrop }) => {
   const { state: canvasState, actions: canvasActions, canvasRef, utils, setContainerElement } = useNodeCanvas();
   const { actions: actionActions } = useEditorActionState();
+  const { settings } = useNodeEditor();
   const containerRef = React.useRef<HTMLDivElement>(null);
   const rawGridPatternId = React.useId();
   const gridPatternId = React.useMemo(() => rawGridPatternId.replace(/[^a-zA-Z0-9_-]/g, "_"), [rawGridPatternId]);
@@ -52,7 +54,9 @@ export const CanvasBase: React.FC<CanvasBaseProps> = ({ children, className, sho
     return () => setContainerElement(null);
   }, [setContainerElement]);
 
-  const shouldShowGrid = showGrid ?? canvasState.gridSettings.showGrid;
+  const currentScale = canvasState.viewport.scale;
+  const shouldShowGrid =
+    (showGrid ?? canvasState.gridSettings.showGrid) && currentScale >= settings.gridVisibilityThreshold;
 
   // Canvas transform based on viewport - optimized string creation
   const canvasTransform = React.useMemo(() => {

src/components/node/NodeViewContainer.tsx

@@ -38,6 +38,8 @@ export type NodeViewContainerProps = {
   nodeRenderer?: (props: NodeRendererProps) => React.ReactNode;
   externalData?: unknown;
   onUpdateNode?: (updates: Partial<Node>) => void;
+  /** Port label visibility - calculated at NodeLayer level for performance */
+  showPortLabels?: boolean;
 };
 
 const NodeViewContainerComponent: React.FC<NodeViewContainerProps> = ({
@@ -59,6 +61,7 @@ const NodeViewContainerComponent: React.FC<NodeViewContainerProps> = ({
   connectedPortIds,
   connectablePorts,
   candidatePortId,
+  showPortLabels,
 }) => {
   const { actions: nodeEditorActions, getNodePorts, getNodeById } = useNodeEditorApi();
   // Use split hooks for better performance
@@ -224,6 +227,7 @@ const NodeViewContainerComponent: React.FC<NodeViewContainerProps> = ({
       connectedPortIds={connectedPortIds}
       connectablePorts={connectablePorts}
       candidatePortId={candidatePortId}
+      showPortLabels={showPortLabels}
     />
   );
 };

src/components/node/NodeViewPresenter.tsx

@@ -66,6 +66,8 @@ export type NodeViewPresenterProps = {
   connectedPortIds?: ReadonlySet<string>;
   connectablePorts?: ConnectablePortsResult;
   candidatePortId?: string;
+  /** Control visibility of port labels. When undefined, derived from zoom level. */
+  showPortLabels?: boolean;
 };
 
 const DEBUG_NODEVIEW_PRESENTER_RERENDERS = false;
@@ -109,6 +111,7 @@ const NodeViewPresenterComponent: React.FC<NodeViewPresenterProps> = ({
   connectedPortIds,
   connectablePorts,
   candidatePortId,
+  showPortLabels,
 }) => {
   const nodeRef = React.useRef<HTMLDivElement>(null);
   const lastTransformRef = React.useRef<Position | null>(null);
@@ -267,6 +270,7 @@ const NodeViewPresenterComponent: React.FC<NodeViewPresenterProps> = ({
         connectablePorts={connectablePorts}
         connectingPortId={connectingPortId}
         candidatePortId={candidatePortId}
+        showLabels={showPortLabels}
       />
 
       {isSelected && !node.locked && (
@@ -390,6 +394,11 @@ const arePresenterPropsEqual = (
     return false;
   }
 
+  if (prevProps.showPortLabels !== nextProps.showPortLabels) {
+    debugLog("showPortLabels changed");
+    return false;
+  }
+
   if (DEBUG_NODEVIEW_PRESENTER_RERENDERS) {
     console.log(`[NodeViewPresenter:${nodeId}] Skipped re-render`);
   }

src/components/node/layer/NodeLayer.tsx

@@ -13,11 +13,13 @@ import {
   useDragNodeIdsSets,
 } from "../../../contexts/composed/canvas/interaction/context";
 import {
+  useNodeEditor,
   useNodeEditorConnectedPortIdsByNode,
   useNodeEditorConnectedPorts,
   useNodeEditorSelector,
   useNodeEditorSortedNodeIds,
 } from "../../../contexts/composed/node-editor/context";
+import { useNodeCanvasViewportScale } from "../../../contexts/composed/canvas/viewport/context";
 import { useGroupManagement } from "../../../contexts/composed/node-editor/hooks/useGroupManagement";
 import { useNodeResize } from "../../../contexts/composed/canvas/interaction/hooks/useNodeResize";
 import { useVisibleNodes } from "../../../contexts/composed/canvas/viewport/hooks/useVisibleNodes";
@@ -58,6 +60,7 @@ type NodeItemProps = {
   candidatePortIdForNode?: string;
   connectedPortIdsByNode: ReadonlyMap<string, ReadonlySet<string>>;
   NodeComponent: React.ComponentType<NodeViewProps>;
+  showPortLabels: boolean;
 };
 
 const NodeItemComponent: React.FC<NodeItemProps> = ({
@@ -79,6 +82,7 @@ const NodeItemComponent: React.FC<NodeItemProps> = ({
   candidatePortIdForNode,
   connectedPortIdsByNode,
   NodeComponent,
+  showPortLabels,
 }) => {
   const node = useNodeEditorSelector((state) => state.nodes[nodeId], { areEqual: (a, b) => a === b });
   if (!node) {
@@ -104,6 +108,7 @@ const NodeItemComponent: React.FC<NodeItemProps> = ({
       hoveredPort={hoveredPortForNode}
       connectedPortIds={connectedPortIdsByNode.get(node.id)}
       candidatePortId={candidatePortIdForNode}
+      showPortLabels={showPortLabels}
     />
   );
 };
@@ -125,6 +130,11 @@ const NodeLayerComponent: React.FC<NodeLayerProps> = ({ doubleClickToEdit }) =>
   const connectionDragMeta = useCanvasInteractionConnectionDragMeta();
   const gridSettings = useNodeCanvasGridSettings();
   const { node: NodeComponent } = useRenderers();
+  const { settings } = useNodeEditor();
+  const scale = useNodeCanvasViewportScale();
+
+  // Calculate showPortLabels once for all nodes
+  const showPortLabels = scale >= settings.portLabelVisibilityThreshold;
 
   // Initialize hooks
   useNodeResize({
@@ -237,6 +247,7 @@ const NodeLayerComponent: React.FC<NodeLayerProps> = ({ doubleClickToEdit }) =>
             candidatePortIdForNode={candidatePortIdForNode}
             connectedPortIdsByNode={connectedPortIdsByNode}
             NodeComponent={NodeComponent}
+            showPortLabels={showPortLabels}
           />
         );
       })}

src/components/ports/NodePortsRenderer.tsx

@@ -8,8 +8,38 @@ import { isPortConnectable } from "../../core/port/connectivity/connectableTypes
 import { PortView } from "./PortView";
 import { useOptionalRenderers } from "../../contexts/RendererContext";
 import { hasPortIdChanged } from "../../core/port/identity/comparators";
+import { NodeCanvasContext } from "../../contexts/composed/canvas/viewport/context";
+import { NodeEditorContext } from "../../contexts/composed/node-editor/context";
+import { useExternalStoreSelector } from "../../hooks/useExternalStoreSelector";
 import styles from "./NodePortsRenderer.module.css";
 
+// Stable fallback functions for when context is not available
+const noopUnsubscribe = () => {};
+const noopSubscribe = () => noopUnsubscribe;
+const defaultGetState = () => ({ viewport: { scale: 1 } });
+const selectScale = (state: { viewport: { scale: number } }) => state.viewport.scale;
+
+/**
+ * Hook to determine if port labels should be visible based on zoom level.
+ * Returns true (show labels) if context is not available, for backwards compatibility.
+ */
+const useShowPortLabels = (): boolean => {
+  const canvasContext = React.useContext(NodeCanvasContext);
+  const editorContext = React.useContext(NodeEditorContext);
+
+  const scale = useExternalStoreSelector(
+    canvasContext?.store.subscribe ?? noopSubscribe,
+    canvasContext?.store.getState ?? defaultGetState,
+    selectScale,
+  );
+
+  if (!canvasContext || !editorContext) {
+    return true;
+  }
+
+  return scale >= editorContext.settings.portLabelVisibilityThreshold;
+};
+
 export type NodePortsRendererProps = {
   ports: Port[];
   onPortPointerDown?: (e: React.PointerEvent, port: Port) => void;
@@ -26,9 +56,10 @@ export type NodePortsRendererProps = {
 };
 
 /**
- * Renders ports for a node
+ * Pure component that renders ports for a node.
+ * Does not subscribe to any context - relies on parent to provide showLabels.
  */
-const NodePortsRendererComponent: React.FC<NodePortsRendererProps> = ({
+const NodePortsRendererPure: React.FC<NodePortsRendererProps & { showLabels: boolean }> = ({
   ports,
   onPortPointerDown,
   onPortPointerUp,
@@ -41,6 +72,7 @@ const NodePortsRendererComponent: React.FC<NodePortsRendererProps> = ({
   connectablePorts,
   connectingPortId,
   candidatePortId,
+  showLabels,
 }) => {
   const renderers = useOptionalRenderers();
   const PortComponent = renderers?.port ?? PortView;
@@ -68,18 +100,39 @@ const NodePortsRendererComponent: React.FC<NodePortsRendererProps> = ({
             isCandidate={candidatePortId === port.id}
             isHovered={hoveredPort?.id === port.id}
             isConnected={connectedPortIds?.has(port.id)}
+            showLabel={showLabels}
           />
         );
       })}
     </div>
   );
 };
 
+/**
+ * Wrapper component that derives showLabels from context.
+ * Use this when you need automatic zoom-based label visibility.
+ */
+const NodePortsRendererWithAutoLabels: React.FC<NodePortsRendererProps> = (props) => {
+  const showLabels = useShowPortLabels();
+  return <NodePortsRendererPure {...props} showLabels={showLabels} />;
+};
+
 // Temporary debug flag - set to true to enable detailed re-render logging
 const DEBUG_NODEPORTSRENDERER_RERENDERS = false;
 
+// Props type with optional showLabels for backwards compatibility
+export type NodePortsRendererPropsWithLabels = NodePortsRendererProps & { showLabels?: boolean };
+
 // Memoized version with custom comparison
-export const NodePortsRenderer = React.memo(NodePortsRendererComponent, (prevProps, nextProps) => {
+export const NodePortsRenderer = React.memo(
+  (props: NodePortsRendererPropsWithLabels) => {
+    // Use showLabels from props if provided, otherwise derive from context
+    if (props.showLabels !== undefined) {
+      return <NodePortsRendererPure {...props} showLabels={props.showLabels} />;
+    }
+    return <NodePortsRendererWithAutoLabels {...props} />;
+  },
+  (prevProps: NodePortsRendererPropsWithLabels, nextProps: NodePortsRendererPropsWithLabels) => {
   // Get nodeId for debugging (from first port if available)
   const nodeId = prevProps.ports?.[0]?.nodeId || nextProps.ports?.[0]?.nodeId || "unknown";
   const debugLog = (reason: string, details?: Record<string, unknown>) => {
@@ -128,10 +181,15 @@ export const NodePortsRenderer = React.memo(NodePortsRendererComponent, (prevPro
     });
     return false;
   }
+  if (prevProps.showLabels !== nextProps.showLabels) {
+    debugLog("showLabels changed", { prev: prevProps.showLabels, next: nextProps.showLabels });
+    return false;
+  }
 
   // Event handlers are assumed to be stable (useCallback)
   if (DEBUG_NODEPORTSRENDERER_RERENDERS) {
     console.log(`[NodePortsRenderer:${nodeId}] Skipped re-render (props are equal)`);
   }
   return true;
-});
+},
+);

src/components/ports/PortView.tsx

@@ -45,6 +45,12 @@ export type PortViewProps = {
    * Visual: inner circle changes to success color (green)
    */
   isConnected?: boolean;
+  /**
+   * Control visibility of port label.
+   * When false, label is hidden (e.g., when zoomed out).
+   * Defaults to true.
+   */
+  showLabel?: boolean;
 };
 
 /**
@@ -64,6 +70,7 @@ export const PortView: React.FC<PortViewProps> = ({
   isCandidate = false,
   isHovered = false,
   isConnected = false,
+  showLabel = true,
 }) => {
   const resizeOverride = useCanvasInteractionSelector(
     (state) => {
@@ -180,14 +187,14 @@ export const PortView: React.FC<PortViewProps> = ({
         title={port.label}
       >
         <div className={styles.portInner} />
-        {port.label && (
+        {port.label && showLabel && (
           <span className={styles.portLabel} data-port-label-position={port.position}>
             {port.label}
           </span>
         )}
       </div>
     ),
-    [port, isConnecting, isConnectable, isCandidate, isHovered, isConnected, portPositionStyle],
+    [port, isConnecting, isConnectable, isCandidate, isHovered, isConnected, portPositionStyle, showLabel],
   );
 
   // Check if there's a custom renderer
@@ -204,6 +211,7 @@ export const PortView: React.FC<PortViewProps> = ({
       isCandidate,
       isHovered,
       isConnected,
+      showLabel,
       position: portPosition
         ? {
             x: portPosition.renderPosition.x,

src/hooks/useSettings.ts

@@ -20,6 +20,8 @@ type Settings = {
   fontSize: number;
   gridSize: number;
   gridOpacity: number;
+  gridVisibilityThreshold: number;
+  portLabelVisibilityThreshold: number;
   canvasBackground: string;
   nodeSearchViewMode: NodeSearchViewMode;
   nodeSearchFilterMode: NodeSearchFilterMode;
@@ -41,6 +43,8 @@ const defaultSettings: Settings = {
   fontSize: 14,
   gridSize: 20,
   gridOpacity: 0.3,
+  gridVisibilityThreshold: 0.3,
+  portLabelVisibilityThreshold: 0.5,
   canvasBackground: "#ffffff",
   nodeSearchViewMode: "list",
   nodeSearchFilterMode: "filter",
@@ -161,6 +165,16 @@ export function useSettings(settingsManager?: SettingsManager): Settings {
       fontSize: getNumberSetting(settingsManager, "appearance.fontSize", defaultSettings.fontSize),
       gridSize: getNumberSetting(settingsManager, "appearance.gridSize", defaultSettings.gridSize),
       gridOpacity: getNumberSetting(settingsManager, "appearance.gridOpacity", defaultSettings.gridOpacity),
+      gridVisibilityThreshold: getNumberSetting(
+        settingsManager,
+        "appearance.gridVisibilityThreshold",
+        defaultSettings.gridVisibilityThreshold,
+      ),
+      portLabelVisibilityThreshold: getNumberSetting(
+        settingsManager,
+        "appearance.portLabelVisibilityThreshold",
+        defaultSettings.portLabelVisibilityThreshold,
+      ),
       canvasBackground: getStringSetting(
         settingsManager,
         "appearance.canvasBackground",