@tscircuit/schematic-viewer 2.0.54 → 2.0.56

package/examples/example17-schematic-ports.fixture.tsx

@@ -0,0 +1,49 @@
+import { SchematicViewer } from "lib/components/SchematicViewer"
+import { renderToCircuitJson } from "lib/dev/render-to-circuit-json"
+
+const circuitJson = renderToCircuitJson(
+  <board width="10mm" height="10mm" routingDisabled>
+    <resistor name="R1" resistance={1000} schX={-2} />
+    <capacitor name="C1" capacitance="1uF" schX={2} schY={2} />
+    <capacitor
+      name="C2"
+      schRotation={90}
+      capacitance="1uF"
+      schX={0}
+      schY={-4}
+    />
+    <chip
+      name="U1"
+      pinLabels={{
+        pin1: "D0",
+        pin2: "D1",
+        pin3: "D2",
+        pin4: "GND",
+        pin5: "D3",
+        pin6: "EN",
+        pin7: "D4",
+        pin8: "VCC",
+      }}
+      footprint="soic8"
+      schX={0}
+      schY={-1.5}
+    />
+
+    <trace from=".R1 .pin2" to=".C1 .pin1" />
+    <trace from=".C1 .pin2" to=".U1 .pin4" />
+    <trace from=".U1 .pin8" to=".C2 .pin1" />
+    <trace from=".C2 .pin2" to=".R1 .pin1" />
+    <trace from=".U1 .pin1" to=".U1 .pin5" />
+  </board>,
+)
+
+export default () => (
+  <SchematicViewer
+    circuitJson={circuitJson}
+    containerStyle={{ height: "100%" }}
+    showSchematicPorts
+    onSchematicPortClicked={({ schematicPortId }) => {
+      console.log("Port clicked:", schematicPortId)
+    }}
+  />
+)

package/examples/example18-live-toggle.fixture.tsx

@@ -0,0 +1,60 @@
+import { useState } from "react"
+import { SchematicViewer } from "lib/components/SchematicViewer"
+import { renderToCircuitJson } from "lib/dev/render-to-circuit-json"
+
+export default () => {
+  const [showDebugGrid, setShowDebugGrid] = useState(true)
+  const [showPorts, setShowPorts] = useState(false)
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
+      <div style={{ padding: 10, display: "flex", gap: 10 }}>
+        <button onClick={() => setShowDebugGrid(!showDebugGrid)}>
+          Debug Grid: {String(showDebugGrid)}
+        </button>
+        <button onClick={() => setShowPorts(!showPorts)}>
+          Schematic Ports: {String(showPorts)}
+        </button>
+      </div>
+      <SchematicViewer
+        circuitJson={renderToCircuitJson(
+          <board width="10mm" height="10mm" routingDisabled>
+            <resistor name="R1" resistance={1000} schX={-2} />
+            <capacitor name="C1" capacitance="1uF" schX={2} schY={2} />
+            <capacitor
+              name="C2"
+              schRotation={90}
+              capacitance="1uF"
+              schX={0}
+              schY={-4}
+            />
+            <chip
+              name="U1"
+              pinLabels={{
+                pin1: "D0",
+                pin2: "D1",
+                pin3: "D2",
+                pin4: "GND",
+                pin5: "D3",
+                pin6: "EN",
+                pin7: "D4",
+                pin8: "VCC",
+              }}
+              footprint="soic8"
+              schX={0}
+              schY={-1.5}
+            />
+
+            <trace from=".R1 .pin2" to=".C1 .pin1" />
+            <trace from=".C1 .pin2" to=".U1 .pin4" />
+            <trace from=".U1 .pin8" to=".C2 .pin1" />
+            <trace from=".C2 .pin2" to=".R1 .pin1" />
+            <trace from=".U1 .pin1" to=".U1 .pin5" />
+          </board>,
+        )}
+        debugGrid={showDebugGrid}
+        showSchematicPorts={showPorts}
+      />
+    </div>
+  )
+}

package/lib/components/SchematicPortMouseTarget.tsx

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import { useMouseEventsOverBoundingBox } from "../hooks/useMouseEventsOverBoundingBox"
+import type { BoundingBoxBounds } from "./MouseTracker"
+import { zIndexMap } from "../utils/z-index-map"
+
+interface RelativeRect {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+interface Measurement {
+  bounds: BoundingBoxBounds
+  rect: RelativeRect
+}
+
+const areMeasurementsEqual = (a: Measurement | null, b: Measurement | null) => {
+  if (!a && !b) return true
+  if (!a || !b) return false
+  return (
+    Math.abs(a.bounds.minX - b.bounds.minX) < 0.5 &&
+    Math.abs(a.bounds.maxX - b.bounds.maxX) < 0.5 &&
+    Math.abs(a.bounds.minY - b.bounds.minY) < 0.5 &&
+    Math.abs(a.bounds.maxY - b.bounds.maxY) < 0.5 &&
+    Math.abs(a.rect.left - b.rect.left) < 0.5 &&
+    Math.abs(a.rect.top - b.rect.top) < 0.5 &&
+    Math.abs(a.rect.width - b.rect.width) < 0.5 &&
+    Math.abs(a.rect.height - b.rect.height) < 0.5
+  )
+}
+
+interface Props {
+  portId: string
+  portLabel?: string
+  svgDivRef: React.RefObject<HTMLDivElement | null>
+  containerRef: React.RefObject<HTMLDivElement | null>
+  onPortClick?: (portId: string, event: MouseEvent) => void
+  onHoverChange?: (portId: string, isHovering: boolean) => void
+  showOutline: boolean
+  circuitJsonKey: string
+}
+
+export const SchematicPortMouseTarget = ({
+  portId,
+  portLabel,
+  svgDivRef,
+  containerRef,
+  onPortClick,
+  onHoverChange,
+  showOutline,
+  circuitJsonKey,
+}: Props) => {
+  const [measurement, setMeasurement] = useState<Measurement | null>(null)
+  const frameRef = useRef<number | null>(null)
+
+  const measure = useCallback(() => {
+    frameRef.current = null
+    const svgDiv = svgDivRef.current
+    const container = containerRef.current
+    if (!svgDiv || !container) {
+      setMeasurement((prev) => (prev ? null : prev))
+      return
+    }
+    const element = svgDiv.querySelector<SVGGraphicsElement | HTMLElement>(
+      `[data-schematic-port-id="${portId}"]`,
+    )
+    if (!element) {
+      setMeasurement((prev) => (prev ? null : prev))
+      return
+    }
+
+    const elementRect = element.getBoundingClientRect()
+    const containerRect = container.getBoundingClientRect()
+
+    // Add some padding around the port for easier interaction
+    const padding = 4
+
+    const nextMeasurement: Measurement = {
+      bounds: {
+        minX: elementRect.left - padding,
+        maxX: elementRect.right + padding,
+        minY: elementRect.top - padding,
+        maxY: elementRect.bottom + padding,
+      },
+      rect: {
+        left: elementRect.left - containerRect.left - padding,
+        top: elementRect.top - containerRect.top - padding,
+        width: elementRect.width + padding * 2,
+        height: elementRect.height + padding * 2,
+      },
+    }
+
+    setMeasurement((prev) =>
+      areMeasurementsEqual(prev, nextMeasurement) ? prev : nextMeasurement,
+    )
+  }, [portId, containerRef, svgDivRef])
+
+  const scheduleMeasure = useCallback(() => {
+    if (frameRef.current !== null) return
+    frameRef.current = window.requestAnimationFrame(measure)
+  }, [measure])
+
+  useEffect(() => {
+    scheduleMeasure()
+  }, [scheduleMeasure, circuitJsonKey])
+
+  useEffect(() => {
+    scheduleMeasure()
+    const svgDiv = svgDivRef.current
+    const container = containerRef.current
+    if (!svgDiv || !container) return
+
+    const resizeObserver =
+      typeof ResizeObserver !== "undefined"
+        ? new ResizeObserver(() => {
+            scheduleMeasure()
+          })
+        : null
+    resizeObserver?.observe(container)
+    resizeObserver?.observe(svgDiv)
+
+    const mutationObserver =
+      typeof MutationObserver !== "undefined"
+        ? new MutationObserver(() => {
+            scheduleMeasure()
+          })
+        : null
+    mutationObserver?.observe(svgDiv, {
+      attributes: true,
+      attributeFilter: ["style", "transform"],
+      subtree: true,
+      childList: true,
+    })
+
+    window.addEventListener("scroll", scheduleMeasure, true)
+    window.addEventListener("resize", scheduleMeasure)
+
+    return () => {
+      resizeObserver?.disconnect()
+      mutationObserver?.disconnect()
+      window.removeEventListener("scroll", scheduleMeasure, true)
+      window.removeEventListener("resize", scheduleMeasure)
+      if (frameRef.current !== null) {
+        cancelAnimationFrame(frameRef.current)
+        frameRef.current = null
+      }
+    }
+  }, [scheduleMeasure, svgDivRef, containerRef])
+
+  const handleClick = useCallback(
+    (event: MouseEvent) => {
+      if (onPortClick) {
+        onPortClick(portId, event)
+      }
+    },
+    [portId, onPortClick],
+  )
+
+  const bounds = measurement?.bounds ?? null
+
+  const { hovering } = useMouseEventsOverBoundingBox({
+    bounds,
+    onClick: onPortClick ? handleClick : undefined,
+  })
+
+  // Notify parent of hover state changes
+  useEffect(() => {
+    if (onHoverChange) {
+      onHoverChange(portId, hovering)
+    }
+  }, [hovering, portId, onHoverChange])
+
+  if (!measurement || !showOutline) {
+    return null
+  }
+
+  const rect = measurement.rect
+
+  return (
+    <>
+      <div
+        style={{
+          position: "absolute",
+          left: rect.left,
+          top: rect.top,
+          width: rect.width,
+          height: rect.height,
+          border: hovering
+            ? "1.5px solid rgba(255, 153, 51, 0.9)"
+            : "1.5px solid rgba(255, 153, 51, 0.3)",
+          backgroundColor: hovering
+            ? "rgba(255, 153, 51, 0.15)"
+            : "rgba(255, 153, 51, 0.05)",
+          borderRadius: "50%",
+          pointerEvents: "none",
+          zIndex: zIndexMap.schematicPortHoverOutline,
+          transition: "border-color 0.15s, background-color 0.15s",
+        }}
+      />
+      {hovering && portLabel && (
+        <div
+          style={{
+            position: "absolute",
+            left: rect.left + rect.width / 2,
+            top: rect.top - 24,
+            transform: "translateX(-50%)",
+            backgroundColor: "rgba(0, 0, 0, 0.85)",
+            color: "white",
+            padding: "4px 8px",
+            borderRadius: "4px",
+            fontSize: "12px",
+            fontFamily: "monospace",
+            whiteSpace: "nowrap",
+            pointerEvents: "none",
+            zIndex: zIndexMap.schematicPortHoverOutline + 1,
+          }}
+        >
+          {portLabel}
+        </div>
+      )}
+    </>
+  )
+}

package/lib/components/SchematicViewer.tsx

@@ -30,6 +30,7 @@ import { getSpiceFromCircuitJson } from "../utils/spice-utils"
 import { getStoredBoolean, setStoredBoolean } from "lib/hooks/useLocalStorage"
 import { MouseTracker } from "./MouseTracker"
 import { SchematicComponentMouseTarget } from "./SchematicComponentMouseTarget"
+import { SchematicPortMouseTarget } from "./SchematicPortMouseTarget"
 
 interface Props {
   circuitJson: CircuitJson
@@ -48,6 +49,11 @@ interface Props {
     schematicComponentId: string
     event: MouseEvent
   }) => void
+  showSchematicPorts?: boolean
+  onSchematicPortClicked?: (options: {
+    schematicPortId: string
+    event: MouseEvent
+  }) => void
 }
 
 export const SchematicViewer = ({
@@ -64,6 +70,8 @@ export const SchematicViewer = ({
   spiceSimulationEnabled = false,
   disableGroups = false,
   onSchematicComponentClicked,
+  showSchematicPorts = false,
+  onSchematicPortClicked,
 }: Props) => {
   if (debug) {
     enableDebug()
@@ -115,7 +123,8 @@ export const SchematicViewer = ({
 
   const [editModeEnabled, setEditModeEnabled] = useState(defaultEditMode)
   const [snapToGrid, setSnapToGrid] = useState(true)
-  const [showGrid, setShowGrid] = useState(debugGrid)
+  const [showGridInternal, setShowGridInternal] = useState(false)
+  const showGrid = debugGrid || showGridInternal
   const [isInteractionEnabled, setIsInteractionEnabled] = useState<boolean>(
     !clickToInteractEnabled,
   )
@@ -139,6 +148,22 @@ export const SchematicViewer = ({
     },
     [],
   )
+
+  const [isHoveringClickablePort, setIsHoveringClickablePort] = useState(false)
+  const hoveringPortsRef = useRef<Set<string>>(new Set())
+
+  const handlePortHoverChange = useCallback(
+    (portId: string, isHovering: boolean) => {
+      if (isHovering) {
+        hoveringPortsRef.current.add(portId)
+      } else {
+        hoveringPortsRef.current.delete(portId)
+      }
+      setIsHoveringClickablePort(hoveringPortsRef.current.size > 0)
+    },
+    [],
+  )
+
   const svgDivRef = useRef<HTMLDivElement>(null)
   const touchStartRef = useRef<{ x: number; y: number } | null>(null)
 
@@ -155,6 +180,32 @@ export const SchematicViewer = ({
     }
   }, [circuitJsonKey, circuitJson])
 
+  const schematicPortsInfo = useMemo(() => {
+    if (!showSchematicPorts) return []
+    try {
+      const ports = su(circuitJson).schematic_port?.list() ?? []
+      return ports.map((port) => {
+        const sourcePort = su(circuitJson).source_port.get(port.source_port_id)
+        const sourceComponent = sourcePort?.source_component_id
+          ? su(circuitJson).source_component.get(sourcePort.source_component_id)
+          : null
+        const componentName = sourceComponent?.name ?? "?"
+        const pinLabel =
+          port.display_pin_label ??
+          (sourcePort as any)?.pin_number ??
+          (sourcePort as any)?.name ??
+          "?"
+        return {
+          portId: port.source_port_id as string,
+          label: `${componentName}.${pinLabel}`,
+        }
+      })
+    } catch (err) {
+      console.error("Failed to derive schematic port info", err)
+      return []
+    }
+  }, [circuitJsonKey, circuitJson, showSchematicPorts])
+
   const handleTouchStart = (e: React.TouchEvent) => {
     const touch = e.touches[0]
     touchStartRef.current = {
@@ -343,6 +394,11 @@ export const SchematicViewer = ({
           {`.schematic-component-clickable [data-schematic-component-id]:hover { cursor: pointer !important; }`}
         </style>
       )}
+      {onSchematicPortClicked && (
+        <style>
+          {`[data-schematic-port-id]:hover { cursor: pointer !important; }`}
+        </style>
+      )}
       <div
         ref={containerRef}
         style={{
@@ -357,7 +413,9 @@ export const SchematicViewer = ({
                 ? "pointer"
                 : isHoveringClickableComponent && onSchematicComponentClicked
                   ? "pointer"
-                  : "grab",
+                  : isHoveringClickablePort && onSchematicPortClicked
+                    ? "pointer"
+                    : "grab",
           minHeight: "300px",
           ...containerStyle,
         }}
@@ -456,7 +514,7 @@ export const SchematicViewer = ({
             }
           }}
           showGrid={showGrid}
-          onToggleGrid={setShowGrid}
+          onToggleGrid={setShowGridInternal}
         />
         {spiceSimulationEnabled && (
           <SpiceSimulationIcon onClick={() => setShowSpiceOverlay(true)} />
@@ -496,6 +554,29 @@ export const SchematicViewer = ({
             />
           ))}
         {svgDiv}
+        {showSchematicPorts &&
+          schematicPortsInfo.map(({ portId, label }) => (
+            <SchematicPortMouseTarget
+              key={portId}
+              portId={portId}
+              portLabel={label}
+              svgDivRef={svgDivRef}
+              containerRef={containerRef}
+              showOutline={true}
+              circuitJsonKey={circuitJsonKey}
+              onHoverChange={handlePortHoverChange}
+              onPortClick={
+                onSchematicPortClicked
+                  ? (id, event) => {
+                      onSchematicPortClicked?.({
+                        schematicPortId: id,
+                        event,
+                      })
+                    }
+                  : undefined
+              }
+            />
+          ))}
       </div>
     </MouseTracker>
   )

package/lib/utils/z-index-map.ts

@@ -7,4 +7,5 @@ export const zIndexMap = {
   viewMenuBackdrop: 54,
   clickToInteractOverlay: 100,
   schematicComponentHoverOutline: 47,
+  schematicPortHoverOutline: 48,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/schematic-viewer",
-  "version": "2.0.54",
+  "version": "2.0.56",
   "main": "dist/index.js",
   "type": "module",
   "scripts": {