circuitjson-toolkit 1.0.16 → 1.1.0

package/src/ui/CircuitJsonSchematicSvgArcPath.mjs

@@ -11,8 +11,12 @@ export class CircuitJsonSchematicSvgArcPath {
      */
     static fromThreePoints(start, mid, end) {
         if (!start || !mid || !end) return ''
-        const circle = CircuitJsonSchematicSvgArcPath.#circle(start, mid, end)
-        if (!circle) {
+        const geometry = CircuitJsonSchematicSvgArcPath.#geometry(
+            start,
+            mid,
+            end
+        )
+        if (!geometry) {
             return (
                 'M ' +
                 CircuitJsonSchematicSvgArcPath.#formatPoint(start) +
@@ -20,6 +24,69 @@ export class CircuitJsonSchematicSvgArcPath {
                 CircuitJsonSchematicSvgArcPath.#formatPoint(end)
             )
         }
+
+        return (
+            'M ' +
+            CircuitJsonSchematicSvgArcPath.#formatPoint(start) +
+            ' A ' +
+            CircuitJsonSchematicSvgArcPath.#formatNumber(
+                geometry.circle.radius
+            ) +
+            ' ' +
+            CircuitJsonSchematicSvgArcPath.#formatNumber(
+                geometry.circle.radius
+            ) +
+            ' 0 ' +
+            geometry.largeArc +
+            ' ' +
+            geometry.sweep +
+            ' ' +
+            CircuitJsonSchematicSvgArcPath.#formatPoint(end)
+        )
+    }
+
+    /**
+     * Resolves the exact axis-aligned bounds of the rendered three-point arc.
+     * @param {{ x: number, y: number } | null} start Start point.
+     * @param {{ x: number, y: number } | null} mid Midpoint on the arc.
+     * @param {{ x: number, y: number } | null} end End point.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null} Arc bounds.
+     */
+    static boundsFromThreePoints(start, mid, end) {
+        if (!start || !mid || !end) return null
+        const geometry = CircuitJsonSchematicSvgArcPath.#geometry(
+            start,
+            mid,
+            end
+        )
+        if (!geometry) {
+            return CircuitJsonSchematicSvgArcPath.#bounds([start, end])
+        }
+        const points = [start, end]
+        for (const angle of [0, Math.PI / 2, Math.PI, (Math.PI * 3) / 2]) {
+            if (
+                !CircuitJsonSchematicSvgArcPath.#containsAngle(geometry, angle)
+            ) {
+                continue
+            }
+            points.push({
+                x: geometry.circle.x + Math.cos(angle) * geometry.circle.radius,
+                y: geometry.circle.y + Math.sin(angle) * geometry.circle.radius
+            })
+        }
+        return CircuitJsonSchematicSvgArcPath.#bounds(points)
+    }
+
+    /**
+     * Resolves the shared circle and directed sweep through three points.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} mid Midpoint on the arc.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {{ circle: { x: number, y: number, radius: number }, startAngle: number, endAngle: number, sweep: 0 | 1, span: number, largeArc: 0 | 1 } | null} Arc geometry.
+     */
+    static #geometry(start, mid, end) {
+        const circle = CircuitJsonSchematicSvgArcPath.#circle(start, mid, end)
+        if (!circle) return null
         const startAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, start)
         const midAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, mid)
         const endAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, end)
@@ -39,22 +106,55 @@ export class CircuitJsonSchematicSvgArcPath {
                       endAngle,
                       startAngle
                   )
-        const largeArc = span > Math.PI ? 1 : 0
+        return {
+            circle,
+            startAngle,
+            endAngle,
+            sweep,
+            span,
+            largeArc: span > Math.PI ? 1 : 0
+        }
+    }
 
-        return (
-            'M ' +
-            CircuitJsonSchematicSvgArcPath.#formatPoint(start) +
-            ' A ' +
-            CircuitJsonSchematicSvgArcPath.#formatNumber(circle.radius) +
-            ' ' +
-            CircuitJsonSchematicSvgArcPath.#formatNumber(circle.radius) +
-            ' 0 ' +
-            largeArc +
-            ' ' +
-            sweep +
-            ' ' +
-            CircuitJsonSchematicSvgArcPath.#formatPoint(end)
-        )
+    /**
+     * Returns whether one cardinal angle lies on the directed arc sweep.
+     * @param {{ startAngle: number, sweep: 0 | 1, span: number }} geometry Arc geometry.
+     * @param {number} angle Candidate angle.
+     * @returns {boolean} Whether the angle is visible.
+     */
+    static #containsAngle(geometry, angle) {
+        const delta =
+            geometry.sweep === 1
+                ? CircuitJsonSchematicSvgArcPath.#positiveDelta(
+                      geometry.startAngle,
+                      angle
+                  )
+                : CircuitJsonSchematicSvgArcPath.#positiveDelta(
+                      angle,
+                      geometry.startAngle
+                  )
+        return delta <= geometry.span + 0.000001
+    }
+
+    /**
+     * Builds finite bounds around a non-empty point list.
+     * @param {{ x: number, y: number }[]} points Points to include.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number }} Bounds.
+     */
+    static #bounds(points) {
+        const bounds = {
+            minX: Infinity,
+            minY: Infinity,
+            maxX: -Infinity,
+            maxY: -Infinity
+        }
+        for (const point of points) {
+            bounds.minX = Math.min(bounds.minX, point.x)
+            bounds.minY = Math.min(bounds.minY, point.y)
+            bounds.maxX = Math.max(bounds.maxX, point.x)
+            bounds.maxY = Math.max(bounds.maxY, point.y)
+        }
+        return bounds
     }
 
     /**

package/src/ui/CircuitJsonSchematicSvgPortMetadata.mjs

@@ -1,3 +1,5 @@
+import { SafeXmlText } from './SafeXmlText.mjs'
+
 /**
  * Resolves schematic port display metadata from linked source ports.
  */
@@ -26,10 +28,10 @@ export class CircuitJsonSchematicSvgPortMetadata {
      */
     static attributes(element, sourcePort) {
         const sourcePortId = String(element.source_port_id || '').trim()
-        const pinNumber = CircuitJsonSchematicSvgPortMetadata.#firstText(
+        const pinNumber = CircuitJsonSchematicSvgPortMetadata.#firstText([
             element.pin_number,
             sourcePort?.pin_number
-        )
+        ])
         const direction = String(
             element.facing_direction || element.direction || ''
         ).trim()
@@ -69,34 +71,83 @@ export class CircuitJsonSchematicSvgPortMetadata {
      * Resolves a visible schematic port label.
      * @param {object} element Schematic port row.
      * @param {object | null} sourcePort Linked source port row.
+     * @param {WeakMap<object, string> | null} [hintCache] Render-scoped hint cache.
      * @returns {string}
      */
-    static label(element, sourcePort) {
-        return CircuitJsonSchematicSvgPortMetadata.#firstText(
+    static label(element, sourcePort, hintCache = null) {
+        const direct = CircuitJsonSchematicSvgPortMetadata.#firstText([
             element.name,
             element.label,
             sourcePort?.name,
             sourcePort?.label,
             sourcePort?.pin_label,
             element.pin_number,
-            sourcePort?.pin_number,
-            ...(Array.isArray(sourcePort?.port_hints)
-                ? sourcePort.port_hints
-                : [])
+            sourcePort?.pin_number
+        ])
+        return direct
+            ? direct
+            : CircuitJsonSchematicSvgPortMetadata.#sourceHint(
+                  sourcePort,
+                  hintCache
+              )
+    }
+
+    /**
+     * Resolves one source-port hint fallback within a single render snapshot.
+     * @param {object | null} sourcePort Source-port row.
+     * @param {WeakMap<object, string> | null} hintCache Render-scoped cache.
+     * @returns {string} First non-empty hint.
+     */
+    static #sourceHint(sourcePort, hintCache) {
+        if (!sourcePort || typeof sourcePort !== 'object') return ''
+        if (hintCache?.has(sourcePort)) {
+            return hintCache.get(sourcePort)
+        }
+        const hints = Array.isArray(sourcePort.port_hints)
+            ? sourcePort.port_hints
+            : []
+        const hint = CircuitJsonSchematicSvgPortMetadata.#firstText(hints)
+        hintCache?.set(sourcePort, hint)
+        return hint
+    }
+
+    /**
+     * Resolves the first non-empty text and whether evaluated values are immutable.
+     * @param {unknown[]} values Candidate values.
+     * @returns {{ text: string, immutable: boolean }} Text metadata.
+     */
+    static #firstTextResult(values) {
+        let immutable = true
+        for (const value of values) {
+            immutable =
+                immutable &&
+                CircuitJsonSchematicSvgPortMetadata.#isImmutableScalar(value)
+            const text = String(value ?? '').trim()
+            if (text) return { text, immutable }
+        }
+        return { text: '', immutable }
+    }
+
+    /**
+     * Returns whether a label value is immutable primitive data.
+     * @param {unknown} value Label value.
+     * @returns {boolean} Whether the value can participate in memoization.
+     */
+    static #isImmutableScalar(value) {
+        return (
+            value === null ||
+            value === undefined ||
+            ['string', 'number', 'boolean', 'bigint'].includes(typeof value)
         )
     }
 
     /**
      * Resolves the first non-empty display text value.
-     * @param {...unknown} values Candidate values.
+     * @param {unknown[]} values Candidate values.
      * @returns {string}
      */
-    static #firstText(...values) {
-        return (
-            values
-                .map((value) => String(value ?? '').trim())
-                .find((value) => value) || ''
-        )
+    static #firstText(values) {
+        return CircuitJsonSchematicSvgPortMetadata.#firstTextResult(values).text
     }
 
     /**
@@ -105,10 +156,6 @@ export class CircuitJsonSchematicSvgPortMetadata {
      * @returns {string}
      */
     static #escapeHtml(value) {
-        return String(value ?? '')
-            .replaceAll('&', '&amp;')
-            .replaceAll('<', '&lt;')
-            .replaceAll('>', '&gt;')
-            .replaceAll('"', '&quot;')
+        return SafeXmlText.escape(value)
     }
 }

package/src/ui/CircuitJsonSchematicSvgPrimitiveAttributes.mjs

@@ -1,3 +1,5 @@
+import { SafeXmlText } from './SafeXmlText.mjs'
+
 /**
  * Builds SVG drawing attributes for schematic primitive rows.
  */
@@ -21,6 +23,8 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
         )
         const dashArray =
             CircuitJsonSchematicSvgPrimitiveAttributes.#dashArray(element)
+        const lineCap =
+            CircuitJsonSchematicSvgPrimitiveAttributes.#lineCap(element)
 
         if (strokeWidth !== null) {
             attributes.push(
@@ -31,20 +35,22 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
                     '"'
             )
         }
-        if (strokeColor) {
+        const safeStroke = SafeSvgPaint.color(strokeColor)
+        const safeFill = SafeSvgPaint.color(fillColor)
+        if (safeStroke) {
             attributes.push(
                 'stroke="' +
                     CircuitJsonSchematicSvgPrimitiveAttributes.#escapeHtml(
-                        strokeColor
+                        safeStroke
                     ) +
                     '"'
             )
         }
-        if (options.fill !== false && fillColor) {
+        if (options.fill !== false && safeFill) {
             attributes.push(
                 'fill="' +
                     CircuitJsonSchematicSvgPrimitiveAttributes.#escapeHtml(
-                        fillColor
+                        safeFill
                     ) +
                     '"'
             )
@@ -58,6 +64,9 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
                     '"'
             )
         }
+        if (lineCap) {
+            attributes.push('stroke-linecap="' + lineCap + '"')
+        }
 
         return attributes.length ? ' ' + attributes.join(' ') : ''
     }
@@ -87,6 +96,22 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
      * @returns {string}
      */
     static #dashArray(element) {
+        const dashLength = CircuitJsonSchematicSvgPrimitiveAttributes.#number(
+            element?.dash_length ?? element?.dashLength
+        )
+        const dashGap = CircuitJsonSchematicSvgPrimitiveAttributes.#number(
+            element?.dash_gap ?? element?.dashGap
+        )
+        if (element?.is_dashed && dashLength !== null) {
+            return [dashLength, dashGap ?? dashLength]
+                .map((entry) =>
+                    CircuitJsonSchematicSvgPrimitiveAttributes.#formatNumber(
+                        entry
+                    )
+                )
+                .join(' ')
+        }
+
         const value =
             element?.stroke_dasharray ??
             element?.strokeDasharray ??
@@ -106,6 +131,20 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
         return element?.is_dashed ? '0.4 0.25' : ''
     }
 
+    /**
+     * Resolves one safe SVG stroke line-cap value.
+     * @param {object} element CircuitJSON element row.
+     * @returns {'butt' | 'round' | 'square' | ''}
+     */
+    static #lineCap(element) {
+        const value = String(
+            element?.stroke_linecap ?? element?.strokeLinecap ?? ''
+        )
+            .trim()
+            .toLowerCase()
+        return ['butt', 'round', 'square'].includes(value) ? value : ''
+    }
+
     /**
      * Formats one SVG number.
      * @param {number} value Number value.
@@ -121,10 +160,7 @@ export class CircuitJsonSchematicSvgPrimitiveAttributes {
      * @returns {string}
      */
     static #escapeHtml(value) {
-        return String(value ?? '')
-            .replaceAll('&', '&')
-            .replaceAll('<', '&lt;')
-            .replaceAll('>', '&gt;')
-            .replaceAll('"', '&quot;')
+        return SafeXmlText.escape(value)
     }
 }
+import { SafeSvgPaint } from './SafeSvgPaint.mjs'