circuitjson-toolkit 1.0.3 → 1.0.16

package/src/ui/CircuitJsonPcbViaSvgRenderer.mjs

@@ -0,0 +1,168 @@
+/**
+ * Renders via-like drilled primitives as SVG shapes.
+ */
+export class CircuitJsonPcbViaSvgRenderer {
+    /**
+     * Renders one via-like primitive.
+     * @param {object} primitive Via-like primitive.
+     * @param {string} attributes Data attributes for the primitive group.
+     * @returns {string}
+     */
+    static render(primitive, attributes = '') {
+        const groupAttributes = attributes ? ' ' + attributes : ''
+        return (
+            '<g class="pcb-via-group"' +
+            groupAttributes +
+            '>' +
+            CircuitJsonPcbViaSvgRenderer.#shape(
+                primitive,
+                'pcb-via',
+                primitive.shape || 'circle',
+                primitive.width || primitive.diameter,
+                primitive.height || primitive.diameter
+            ) +
+            CircuitJsonPcbViaSvgRenderer.#shape(
+                primitive,
+                'pcb-via__hole',
+                primitive.holeShape || 'circle',
+                primitive.holeWidth || primitive.holeDiameter,
+                primitive.holeHeight || primitive.holeDiameter
+            ) +
+            '</g>'
+        )
+    }
+
+    /**
+     * Renders one centered SVG shape.
+     * @param {object} primitive Via-like primitive.
+     * @param {string} baseClass Base CSS class.
+     * @param {string} shape Shape name.
+     * @param {number} width Shape width.
+     * @param {number} height Shape height.
+     * @returns {string}
+     */
+    static #shape(primitive, baseClass, shape, width, height) {
+        const normalizedShape = String(shape || 'circle').toLowerCase()
+        const className =
+            baseClass +
+            ' ' +
+            baseClass.replace('__', '-') +
+            '--' +
+            CircuitJsonPcbViaSvgRenderer.#escapeHtml(normalizedShape)
+
+        if (normalizedShape === 'circle') {
+            return (
+                '<circle class="' +
+                className +
+                '" cx="' +
+                CircuitJsonPcbViaSvgRenderer.#formatNumber(primitive.x) +
+                '" cy="' +
+                CircuitJsonPcbViaSvgRenderer.#formatNumber(primitive.y) +
+                '" r="' +
+                CircuitJsonPcbViaSvgRenderer.#formatNumber(width / 2) +
+                '"></circle>'
+            )
+        }
+
+        if (
+            normalizedShape === 'polygon' &&
+            Array.isArray(primitive.points) &&
+            primitive.points.length >= 3
+        ) {
+            return (
+                '<polygon class="' +
+                className +
+                '" points="' +
+                CircuitJsonPcbViaSvgRenderer.#escapeHtml(
+                    CircuitJsonPcbViaSvgRenderer.#pointsAttribute(
+                        primitive.points
+                    )
+                ) +
+                '"></polygon>'
+            )
+        }
+
+        return (
+            '<rect class="' +
+            className +
+            '" x="' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(
+                primitive.x - width / 2
+            ) +
+            '" y="' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(
+                primitive.y - height / 2
+            ) +
+            '" width="' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(width) +
+            '" height="' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(height) +
+            '" rx="' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(
+                normalizedShape === 'pill' ? Math.min(width, height) / 2 : 0
+            ) +
+            '"' +
+            CircuitJsonPcbViaSvgRenderer.#rotationAttribute(primitive) +
+            '></rect>'
+        )
+    }
+
+    /**
+     * Builds a rotation transform attribute.
+     * @param {object} primitive Via-like primitive.
+     * @returns {string}
+     */
+    static #rotationAttribute(primitive) {
+        const rotation = Number(primitive.rotation || 0)
+        if (!Number.isFinite(rotation) || rotation === 0) return ''
+        return (
+            ' transform="rotate(' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(rotation) +
+            ' ' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(primitive.x) +
+            ' ' +
+            CircuitJsonPcbViaSvgRenderer.#formatNumber(primitive.y) +
+            ')"'
+        )
+    }
+
+    /**
+     * Builds a polygon points attribute.
+     * @param {{ x: number, y: number }[]} points Point rows.
+     * @returns {string}
+     */
+    static #pointsAttribute(points) {
+        return points
+            .map(
+                (point) =>
+                    CircuitJsonPcbViaSvgRenderer.#formatNumber(point.x) +
+                    ',' +
+                    CircuitJsonPcbViaSvgRenderer.#formatNumber(point.y)
+            )
+            .join(' ')
+    }
+
+    /**
+     * Formats a number for SVG output.
+     * @param {number} value Numeric value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        const number = Number(value)
+        if (!Number.isFinite(number)) return '0'
+        return String(Math.round(number * 1_000_000) / 1_000_000)
+    }
+
+    /**
+     * Escapes text for HTML attributes.
+     * @param {unknown} value Raw value.
+     * @returns {string}
+     */
+    static #escapeHtml(value) {
+        return String(value ?? '')
+            .replaceAll('&', '&amp;')
+            .replaceAll('"', '&quot;')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+    }
+}

package/src/ui/CircuitJsonSchematicSvgArcPath.mjs

@@ -0,0 +1,138 @@
+/**
+ * Builds SVG path data for schematic arcs.
+ */
+export class CircuitJsonSchematicSvgArcPath {
+    /**
+     * Builds arc path data from start, mid, and end points.
+     * @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 {string}
+     */
+    static fromThreePoints(start, mid, end) {
+        if (!start || !mid || !end) return ''
+        const circle = CircuitJsonSchematicSvgArcPath.#circle(start, mid, end)
+        if (!circle) {
+            return (
+                'M ' +
+                CircuitJsonSchematicSvgArcPath.#formatPoint(start) +
+                ' L ' +
+                CircuitJsonSchematicSvgArcPath.#formatPoint(end)
+            )
+        }
+        const startAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, start)
+        const midAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, mid)
+        const endAngle = CircuitJsonSchematicSvgArcPath.#angle(circle, end)
+        const clockwiseSpan = CircuitJsonSchematicSvgArcPath.#positiveDelta(
+            startAngle,
+            endAngle
+        )
+        const clockwiseMid = CircuitJsonSchematicSvgArcPath.#positiveDelta(
+            startAngle,
+            midAngle
+        )
+        const sweep = clockwiseMid <= clockwiseSpan + 0.000001 ? 1 : 0
+        const span =
+            sweep === 1
+                ? clockwiseSpan
+                : CircuitJsonSchematicSvgArcPath.#positiveDelta(
+                      endAngle,
+                      startAngle
+                  )
+        const 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)
+        )
+    }
+
+    /**
+     * Resolves the circle through three points.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} mid Midpoint.
+     * @param {{ x: number, y: number }} end End point.
+     * @returns {{ x: number, y: number, radius: number } | null}
+     */
+    static #circle(start, mid, end) {
+        const denominator =
+            2 *
+            (start.x * (mid.y - end.y) +
+                mid.x * (end.y - start.y) +
+                end.x * (start.y - mid.y))
+        if (Math.abs(denominator) < 0.000001) return null
+
+        const startLength = start.x * start.x + start.y * start.y
+        const midLength = mid.x * mid.x + mid.y * mid.y
+        const endLength = end.x * end.x + end.y * end.y
+        const x =
+            (startLength * (mid.y - end.y) +
+                midLength * (end.y - start.y) +
+                endLength * (start.y - mid.y)) /
+            denominator
+        const y =
+            (startLength * (end.x - mid.x) +
+                midLength * (start.x - end.x) +
+                endLength * (mid.x - start.x)) /
+            denominator
+        const radius = Math.hypot(start.x - x, start.y - y)
+
+        return Number.isFinite(radius) ? { x, y, radius } : null
+    }
+
+    /**
+     * Resolves the angle from a circle center to a point.
+     * @param {{ x: number, y: number }} center Circle center.
+     * @param {{ x: number, y: number }} point Point on circle.
+     * @returns {number}
+     */
+    static #angle(center, point) {
+        return Math.atan2(point.y - center.y, point.x - center.x)
+    }
+
+    /**
+     * Resolves the positive angular delta from start to end.
+     * @param {number} start Start angle.
+     * @param {number} end End angle.
+     * @returns {number}
+     */
+    static #positiveDelta(start, end) {
+        const full = Math.PI * 2
+        return (((end - start) % full) + full) % full
+    }
+
+    /**
+     * Formats one point for SVG path data.
+     * @param {{ x: number, y: number }} point Point.
+     * @returns {string}
+     */
+    static #formatPoint(point) {
+        return (
+            CircuitJsonSchematicSvgArcPath.#formatNumber(point.x) +
+            ' ' +
+            CircuitJsonSchematicSvgArcPath.#formatNumber(point.y)
+        )
+    }
+
+    /**
+     * Formats one SVG number.
+     * @param {number} value Number value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        const number = Number(value)
+        const integer = Math.round(number)
+        if (Math.abs(number - integer) < 0.000001) return String(integer)
+        return Number(number.toFixed(6)).toString()
+    }
+}

package/src/ui/CircuitJsonSchematicSvgPortMetadata.mjs

@@ -0,0 +1,114 @@
+/**
+ * Resolves schematic port display metadata from linked source ports.
+ */
+export class CircuitJsonSchematicSvgPortMetadata {
+    /**
+     * Builds source port lookup rows.
+     * @param {object[]} sourcePorts Source port rows.
+     * @returns {Map<string, object>}
+     */
+    static sourcePorts(sourcePorts) {
+        return new Map(
+            sourcePorts
+                .map((element) => [
+                    String(element.source_port_id || '').trim(),
+                    element
+                ])
+                .filter(([sourcePortId]) => sourcePortId)
+        )
+    }
+
+    /**
+     * Builds the schematic port group attributes.
+     * @param {object} element Schematic port row.
+     * @param {object | null} sourcePort Linked source port row.
+     * @returns {string}
+     */
+    static attributes(element, sourcePort) {
+        const sourcePortId = String(element.source_port_id || '').trim()
+        const pinNumber = CircuitJsonSchematicSvgPortMetadata.#firstText(
+            element.pin_number,
+            sourcePort?.pin_number
+        )
+        const direction = String(
+            element.facing_direction || element.direction || ''
+        ).trim()
+        const attributes = [
+            'class="schematic-port"',
+            'data-schematic-port-id="' +
+                CircuitJsonSchematicSvgPortMetadata.#escapeHtml(
+                    element.schematic_port_id || ''
+                ) +
+                '"',
+            'data-facing-direction="' +
+                CircuitJsonSchematicSvgPortMetadata.#escapeHtml(direction) +
+                '"'
+        ]
+
+        if (sourcePortId) {
+            attributes.push(
+                'data-source-port-id="' +
+                    CircuitJsonSchematicSvgPortMetadata.#escapeHtml(
+                        sourcePortId
+                    ) +
+                    '"'
+            )
+        }
+        if (pinNumber) {
+            attributes.push(
+                'data-pin-number="' +
+                    CircuitJsonSchematicSvgPortMetadata.#escapeHtml(pinNumber) +
+                    '"'
+            )
+        }
+
+        return attributes.join(' ')
+    }
+
+    /**
+     * Resolves a visible schematic port label.
+     * @param {object} element Schematic port row.
+     * @param {object | null} sourcePort Linked source port row.
+     * @returns {string}
+     */
+    static label(element, sourcePort) {
+        return 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
+                : [])
+        )
+    }
+
+    /**
+     * Resolves the first non-empty display text value.
+     * @param {...unknown} values Candidate values.
+     * @returns {string}
+     */
+    static #firstText(...values) {
+        return (
+            values
+                .map((value) => String(value ?? '').trim())
+                .find((value) => value) || ''
+        )
+    }
+
+    /**
+     * Escapes markup text.
+     * @param {unknown} value Raw value.
+     * @returns {string}
+     */
+    static #escapeHtml(value) {
+        return String(value ?? '')
+            .replaceAll('&', '&amp;')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+            .replaceAll('"', '&quot;')
+    }
+}

package/src/ui/CircuitJsonSchematicSvgPrimitiveAttributes.mjs

@@ -0,0 +1,130 @@
+/**
+ * Builds SVG drawing attributes for schematic primitive rows.
+ */
+export class CircuitJsonSchematicSvgPrimitiveAttributes {
+    /**
+     * Builds optional SVG attributes from common drawing style fields.
+     * @param {object} element CircuitJSON element row.
+     * @param {{ fill?: boolean }} [options] Attribute options.
+     * @returns {string}
+     */
+    static attributes(element, options = {}) {
+        const attributes = []
+        const strokeWidth = CircuitJsonSchematicSvgPrimitiveAttributes.#number(
+            element?.stroke_width ?? element?.strokeWidth
+        )
+        const strokeColor = CircuitJsonSchematicSvgPrimitiveAttributes.#text(
+            element?.stroke_color ?? element?.strokeColor ?? element?.color
+        )
+        const fillColor = CircuitJsonSchematicSvgPrimitiveAttributes.#text(
+            element?.fill_color ?? element?.fillColor
+        )
+        const dashArray =
+            CircuitJsonSchematicSvgPrimitiveAttributes.#dashArray(element)
+
+        if (strokeWidth !== null) {
+            attributes.push(
+                'stroke-width="' +
+                    CircuitJsonSchematicSvgPrimitiveAttributes.#formatNumber(
+                        strokeWidth
+                    ) +
+                    '"'
+            )
+        }
+        if (strokeColor) {
+            attributes.push(
+                'stroke="' +
+                    CircuitJsonSchematicSvgPrimitiveAttributes.#escapeHtml(
+                        strokeColor
+                    ) +
+                    '"'
+            )
+        }
+        if (options.fill !== false && fillColor) {
+            attributes.push(
+                'fill="' +
+                    CircuitJsonSchematicSvgPrimitiveAttributes.#escapeHtml(
+                        fillColor
+                    ) +
+                    '"'
+            )
+        }
+        if (dashArray) {
+            attributes.push(
+                'stroke-dasharray="' +
+                    CircuitJsonSchematicSvgPrimitiveAttributes.#escapeHtml(
+                        dashArray
+                    ) +
+                    '"'
+            )
+        }
+
+        return attributes.length ? ' ' + attributes.join(' ') : ''
+    }
+
+    /**
+     * Resolves a finite number.
+     * @param {unknown} value Number candidate.
+     * @returns {number | null}
+     */
+    static #number(value) {
+        const number = Number(value)
+        return Number.isFinite(number) ? number : null
+    }
+
+    /**
+     * Resolves non-empty text.
+     * @param {unknown} value Text candidate.
+     * @returns {string}
+     */
+    static #text(value) {
+        return String(value ?? '').trim()
+    }
+
+    /**
+     * Resolves a stroke dash array.
+     * @param {object} element CircuitJSON element row.
+     * @returns {string}
+     */
+    static #dashArray(element) {
+        const value =
+            element?.stroke_dasharray ??
+            element?.strokeDasharray ??
+            element?.dash_pattern ??
+            element?.dashPattern
+        const values = Array.isArray(value) ? value : [value]
+        const parts = values
+            .map((entry) =>
+                CircuitJsonSchematicSvgPrimitiveAttributes.#number(entry)
+            )
+            .filter((entry) => entry !== null)
+            .map((entry) =>
+                CircuitJsonSchematicSvgPrimitiveAttributes.#formatNumber(entry)
+            )
+
+        if (parts.length) return parts.join(' ')
+        return element?.is_dashed ? '0.4 0.25' : ''
+    }
+
+    /**
+     * Formats one SVG number.
+     * @param {number} value Number value.
+     * @returns {string}
+     */
+    static #formatNumber(value) {
+        return Number(Number(value).toFixed(6)).toString()
+    }
+
+    /**
+     * Escapes markup text.
+     * @param {unknown} value Raw value.
+     * @returns {string}
+     */
+    static #escapeHtml(value) {
+        return String(value ?? '')
+            .replaceAll('&', '&')
+            .replaceAll('<', '&lt;')
+            .replaceAll('>', '&gt;')
+            .replaceAll('"', '&quot;')
+    }
+}