circuitjson-toolkit 1.0.16 → 1.1.0

package/src/ui/CircuitJsonSchematicDebugRenderer.mjs

@@ -0,0 +1,164 @@
+import { CircuitJsonUnits } from '../core/CircuitJsonUnits.mjs'
+import { SafeXmlText } from './SafeXmlText.mjs'
+
+/**
+ * Renders every standard CircuitJSON schematic debug-object variant.
+ */
+export class CircuitJsonSchematicDebugRenderer {
+    /**
+     * Renders one debug object or an empty string for invalid geometry.
+     * @param {object} element Debug element.
+     * @returns {string} Debug SVG group.
+     */
+    static render(element) {
+        if (
+            element.shape === undefined ||
+            element.legacy_shape_omitted === true
+        ) {
+            return CircuitJsonSchematicDebugRenderer.#legacyRect(element)
+        }
+        const shape = String(element.shape || 'rect')
+        const geometry = CircuitJsonSchematicDebugRenderer.#geometry(
+            element,
+            shape
+        )
+        if (!geometry) return ''
+        const label = String(element.label ?? element.message ?? '').trim()
+        return (
+            '<g class="schematic-debug-object" data-schematic-debug-object-id="' +
+            CircuitJsonSchematicDebugRenderer.#escape(
+                element.schematic_debug_object_id || ''
+            ) +
+            '"><title>' +
+            CircuitJsonSchematicDebugRenderer.#escape(label) +
+            '</title>' +
+            geometry.markup +
+            '<text x="' +
+            CircuitJsonSchematicDebugRenderer.#number(geometry.label.x) +
+            '" y="' +
+            CircuitJsonSchematicDebugRenderer.#number(geometry.label.y) +
+            '" text-anchor="middle" dominant-baseline="central">' +
+            CircuitJsonSchematicDebugRenderer.#escape(label) +
+            '</text></g>'
+        )
+    }
+
+    /**
+     * Preserves the original unqualified rectangle markup byte-for-byte.
+     * @param {object} element Legacy debug element.
+     * @returns {string} Legacy SVG group.
+     */
+    static #legacyRect(element) {
+        const center = CircuitJsonUnits.optionalPoint(element.center)
+        const size = CircuitJsonUnits.optionalSize(element.size || element)
+        if (!center || !size) return ''
+        const message = String(element.message || '').trim()
+        return (
+            '<g class="schematic-debug-object" data-schematic-debug-object-id="' +
+            CircuitJsonSchematicDebugRenderer.#escape(
+                element.schematic_debug_object_id || ''
+            ) +
+            '"><title>' +
+            CircuitJsonSchematicDebugRenderer.#escape(message) +
+            '</title><rect x="' +
+            CircuitJsonSchematicDebugRenderer.#number(
+                center.x - size.width / 2
+            ) +
+            '" y="' +
+            CircuitJsonSchematicDebugRenderer.#number(
+                center.y - size.height / 2
+            ) +
+            '" width="' +
+            CircuitJsonSchematicDebugRenderer.#number(size.width) +
+            '" height="' +
+            CircuitJsonSchematicDebugRenderer.#number(size.height) +
+            '"></rect><text x="' +
+            CircuitJsonSchematicDebugRenderer.#number(center.x) +
+            '" y="' +
+            CircuitJsonSchematicDebugRenderer.#number(center.y) +
+            '" text-anchor="middle" dominant-baseline="central">' +
+            CircuitJsonSchematicDebugRenderer.#escape(message) +
+            '</text></g>'
+        )
+    }
+
+    /**
+     * Builds variant geometry and its label anchor.
+     * @param {object} element Debug element.
+     * @param {string} shape Standard shape discriminant.
+     * @returns {{ markup: string, label: { x: number, y: number } } | null} Geometry.
+     */
+    static #geometry(element, shape) {
+        if (shape === 'line') {
+            const start = CircuitJsonUnits.optionalPoint(element.start)
+            const end = CircuitJsonUnits.optionalPoint(element.end)
+            if (!start || !end) return null
+            return {
+                markup:
+                    '<line class="schematic-debug-object__line" x1="' +
+                    CircuitJsonSchematicDebugRenderer.#number(start.x) +
+                    '" y1="' +
+                    CircuitJsonSchematicDebugRenderer.#number(start.y) +
+                    '" x2="' +
+                    CircuitJsonSchematicDebugRenderer.#number(end.x) +
+                    '" y2="' +
+                    CircuitJsonSchematicDebugRenderer.#number(end.y) +
+                    '"></line>',
+                label: { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 }
+            }
+        }
+        const center = CircuitJsonUnits.optionalPoint(element.center)
+        if (!center) return null
+        if (shape === 'point') {
+            return {
+                markup:
+                    '<circle class="schematic-debug-object__point" cx="' +
+                    CircuitJsonSchematicDebugRenderer.#number(center.x) +
+                    '" cy="' +
+                    CircuitJsonSchematicDebugRenderer.#number(center.y) +
+                    '" r="0.25"></circle>',
+                label: center
+            }
+        }
+        const size = CircuitJsonUnits.optionalSize(element.size || element)
+        if (!size) return null
+        return {
+            markup:
+                '<rect class="schematic-debug-object__rect" x="' +
+                CircuitJsonSchematicDebugRenderer.#number(
+                    center.x - size.width / 2
+                ) +
+                '" y="' +
+                CircuitJsonSchematicDebugRenderer.#number(
+                    center.y - size.height / 2
+                ) +
+                '" width="' +
+                CircuitJsonSchematicDebugRenderer.#number(size.width) +
+                '" height="' +
+                CircuitJsonSchematicDebugRenderer.#number(size.height) +
+                '"></rect>',
+            label: center
+        }
+    }
+
+    /**
+     * Formats one finite SVG number.
+     * @param {unknown} value Number candidate.
+     * @returns {string} SVG number.
+     */
+    static #number(value) {
+        const number = Number(value)
+        return Number.isFinite(number)
+            ? Number(number.toFixed(6)).toString()
+            : '0'
+    }
+
+    /**
+     * Escapes XML text and attribute data.
+     * @param {unknown} value Text candidate.
+     * @returns {string} Escaped text.
+     */
+    static #escape(value) {
+        return SafeXmlText.escape(value)
+    }
+}

package/src/ui/CircuitJsonSchematicImageSvgRenderer.mjs

@@ -0,0 +1,210 @@
+import { BinaryDataSnapshot } from '../core/context/BinaryDataSnapshot.mjs'
+import { CircuitJsonUnits } from '../core/CircuitJsonUnits.mjs'
+import { SafeXmlText } from './SafeXmlText.mjs'
+
+const IMAGE_MEDIA_TYPES = new Set([
+    'image/bmp',
+    'image/gif',
+    'image/jpeg',
+    'image/png',
+    'image/webp'
+])
+const BASE64_ALPHABET =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+/** Renders canonical asset-backed schematic images into deterministic SVG. */
+export class CircuitJsonSchematicImageSvgRenderer {
+    /**
+     * Renders every resolvable canonical image in authored order.
+     * @param {object[]} images Canonical schematic image rows.
+     * @param {object[]} assets Canonical document assets.
+     * @returns {string} SVG image group or an empty string.
+     */
+    static render(images, assets) {
+        const byId = CircuitJsonSchematicImageSvgRenderer.#assetIndex(
+            assets || []
+        )
+        const markup = (images || [])
+            .map((image, index) => ({ image, index }))
+            .sort(
+                (left, right) =>
+                    CircuitJsonSchematicImageSvgRenderer.#order(left.image) -
+                        CircuitJsonSchematicImageSvgRenderer.#order(
+                            right.image
+                        ) || left.index - right.index
+            )
+            .map(({ image }) =>
+                CircuitJsonSchematicImageSvgRenderer.#image(
+                    image,
+                    byId.get(String(image.asset_id || ''))
+                )
+            )
+            .filter(Boolean)
+        return markup.length
+            ? '<g class="schematic-images">' + markup.join('') + '</g>'
+            : ''
+    }
+
+    /**
+     * Builds an exact asset-id index and marks duplicate ids ambiguous.
+     * @param {object[]} assets Canonical assets.
+     * @returns {Map<string, object | null>} Assets by exact id.
+     */
+    static #assetIndex(assets) {
+        const byId = new Map()
+        for (const asset of assets) {
+            const id = String(asset?.id || '')
+            if (!id) continue
+            byId.set(id, byId.has(id) ? null : asset)
+        }
+        return byId
+    }
+
+    /**
+     * Renders one image when its exact payload is available.
+     * @param {object} image Canonical image row.
+     * @param {object | null | undefined} asset Resolved asset.
+     * @returns {string} SVG image markup or an empty string.
+     */
+    static #image(image, asset) {
+        if (!asset || asset.kind !== 'schematic-image') return ''
+        const mediaType = String(asset.mediaType || '').toLowerCase()
+        if (!IMAGE_MEDIA_TYPES.has(mediaType)) return ''
+        const bytes = CircuitJsonSchematicImageSvgRenderer.#assetBytes(asset)
+        if (!bytes?.byteLength) return ''
+        const center = CircuitJsonUnits.optionalPoint(image.center)
+        const size = CircuitJsonUnits.optionalSize(image.size)
+        if (!center || !size || size.width <= 0 || size.height <= 0) return ''
+        const rotation = CircuitJsonUnits.angle(image.rotation, 0)
+        const opacity = CircuitJsonSchematicImageSvgRenderer.#opacity(
+            image.opacity
+        )
+        const attributes = [
+            'class="schematic-image"',
+            'data-schematic-image-id="' +
+                SafeXmlText.escape(image.schematic_image_id || '') +
+                '"',
+            'data-asset-id="' + SafeXmlText.escape(image.asset_id || '') + '"',
+            'x="' +
+                CircuitJsonSchematicImageSvgRenderer.#number(
+                    center.x - size.width / 2
+                ) +
+                '"',
+            'y="' +
+                CircuitJsonSchematicImageSvgRenderer.#number(
+                    center.y - size.height / 2
+                ) +
+                '"',
+            'width="' +
+                CircuitJsonSchematicImageSvgRenderer.#number(size.width) +
+                '"',
+            'height="' +
+                CircuitJsonSchematicImageSvgRenderer.#number(size.height) +
+                '"',
+            'href="data:' +
+                mediaType +
+                ';base64,' +
+                CircuitJsonSchematicImageSvgRenderer.#base64(bytes) +
+                '"',
+            'preserveAspectRatio="' +
+                (image.preserve_aspect_ratio === false
+                    ? 'none'
+                    : 'xMidYMid meet') +
+                '"'
+        ]
+        if (rotation) {
+            attributes.push(
+                'transform="rotate(' +
+                    CircuitJsonSchematicImageSvgRenderer.#number(rotation) +
+                    ' ' +
+                    CircuitJsonSchematicImageSvgRenderer.#number(center.x) +
+                    ' ' +
+                    CircuitJsonSchematicImageSvgRenderer.#number(center.y) +
+                    ')"'
+            )
+        }
+        if (opacity !== null) {
+            attributes.push(
+                'opacity="' +
+                    CircuitJsonSchematicImageSvgRenderer.#number(opacity) +
+                    '"'
+            )
+        }
+        return '<image ' + attributes.join(' ') + '></image>'
+    }
+
+    /**
+     * Reads one exact binary asset range without accepting string payloads.
+     * @param {object} asset Canonical asset.
+     * @returns {Uint8Array | null} Isolated bytes.
+     */
+    static #assetBytes(asset) {
+        let data
+        try {
+            data = asset.data
+        } catch {
+            return null
+        }
+        const range = BinaryDataSnapshot.describe(data)
+        return range ? BinaryDataSnapshot.copyBytes(data, range) : null
+    }
+
+    /**
+     * Encodes exact bytes without Node-only globals.
+     * @param {Uint8Array} bytes Binary bytes.
+     * @returns {string} RFC 4648 base64 text.
+     */
+    static #base64(bytes) {
+        let result = ''
+        for (let index = 0; index < bytes.length; index += 3) {
+            const first = bytes[index]
+            const hasSecond = index + 1 < bytes.length
+            const hasThird = index + 2 < bytes.length
+            const second = hasSecond ? bytes[index + 1] : 0
+            const third = hasThird ? bytes[index + 2] : 0
+            const bits = (first << 16) | (second << 8) | third
+            result += BASE64_ALPHABET[(bits >>> 18) & 63]
+            result += BASE64_ALPHABET[(bits >>> 12) & 63]
+            result += hasSecond ? BASE64_ALPHABET[(bits >>> 6) & 63] : '='
+            result += hasThird ? BASE64_ALPHABET[bits & 63] : '='
+        }
+        return result
+    }
+
+    /**
+     * Resolves a valid optional opacity.
+     * @param {unknown} value Candidate.
+     * @returns {number | null} Opacity or null.
+     */
+    static #opacity(value) {
+        return typeof value === 'number' &&
+            Number.isFinite(value) &&
+            value >= 0 &&
+            value <= 1
+            ? value
+            : null
+    }
+
+    /**
+     * Resolves an authored render order.
+     * @param {object} image Image row.
+     * @returns {number} Sort value.
+     */
+    static #order(image) {
+        return Number.isSafeInteger(image?.render_order)
+            ? image.render_order
+            : Number.MAX_SAFE_INTEGER
+    }
+
+    /**
+     * Formats one deterministic SVG number.
+     * @param {number} value Number value.
+     * @returns {string} SVG number.
+     */
+    static #number(value) {
+        return Number(Number(value).toFixed(6)).toString()
+    }
+}
+
+Object.freeze(CircuitJsonSchematicImageSvgRenderer.prototype)
+Object.freeze(CircuitJsonSchematicImageSvgRenderer)

package/src/ui/CircuitJsonSchematicLineRenderer.mjs

@@ -0,0 +1,86 @@
+import { CircuitJsonUnits } from '../core/CircuitJsonUnits.mjs'
+import { CircuitJsonSchematicSvgPrimitiveAttributes } from './CircuitJsonSchematicSvgPrimitiveAttributes.mjs'
+
+/**
+ * Renders standard trace edges while preserving legacy line aliases.
+ */
+export class CircuitJsonSchematicLineRenderer {
+    /**
+     * Renders all usable standard edges or one legacy fallback segment.
+     * @param {object} element Line or trace element.
+     * @returns {string[]} SVG line elements.
+     */
+    static render(element) {
+        if (
+            element.type === 'schematic_trace' &&
+            Array.isArray(element.edges)
+        ) {
+            const edges = element.edges
+                .map((edge) =>
+                    CircuitJsonSchematicLineRenderer.#segment(
+                        element,
+                        edge?.from,
+                        edge?.to
+                    )
+                )
+                .filter(Boolean)
+            if (edges.length) return edges
+        }
+        const fallback = CircuitJsonSchematicLineRenderer.#segment(element)
+        return fallback ? [fallback] : []
+    }
+
+    /**
+     * Renders one line segment from explicit endpoints or legacy aliases.
+     * @param {object} element Source element.
+     * @param {unknown} [startValue] Standard edge start.
+     * @param {unknown} [endValue] Standard edge end.
+     * @returns {string} SVG line or empty string.
+     */
+    static #segment(element, startValue, endValue) {
+        const start = CircuitJsonUnits.optionalPoint(
+            startValue !== undefined
+                ? startValue
+                : {
+                      x: element.x1 ?? element.start?.x,
+                      y: element.y1 ?? element.start?.y
+                  }
+        )
+        const end = CircuitJsonUnits.optionalPoint(
+            endValue !== undefined
+                ? endValue
+                : {
+                      x: element.x2 ?? element.end?.x,
+                      y: element.y2 ?? element.end?.y
+                  }
+        )
+        if (!start || !end) return ''
+        return (
+            '<line class="schematic-wire" x1="' +
+            CircuitJsonSchematicLineRenderer.#number(start.x) +
+            '" y1="' +
+            CircuitJsonSchematicLineRenderer.#number(start.y) +
+            '" x2="' +
+            CircuitJsonSchematicLineRenderer.#number(end.x) +
+            '" y2="' +
+            CircuitJsonSchematicLineRenderer.#number(end.y) +
+            '"' +
+            CircuitJsonSchematicSvgPrimitiveAttributes.attributes(element, {
+                fill: false
+            }) +
+            '></line>'
+        )
+    }
+
+    /**
+     * Formats one finite SVG number.
+     * @param {unknown} value Number candidate.
+     * @returns {string} SVG number.
+     */
+    static #number(value) {
+        const number = Number(value)
+        return Number.isFinite(number)
+            ? Number(number.toFixed(6)).toString()
+            : '0'
+    }
+}

package/src/ui/CircuitJsonSchematicSheetSymbolSvgRenderer.mjs

@@ -0,0 +1,98 @@
+import { CircuitJsonUnits } from '../core/CircuitJsonUnits.mjs'
+import { CircuitJsonSchematicSvgPrimitiveAttributes } from './CircuitJsonSchematicSvgPrimitiveAttributes.mjs'
+import { SafeXmlText } from './SafeXmlText.mjs'
+
+/** Renders hierarchical child-sheet symbols without treating them as pages. */
+export class CircuitJsonSchematicSheetSymbolSvgRenderer {
+    /**
+     * Renders child-sheet symbols in their authored order.
+     * @param {object[]} symbols Canonical sheet-symbol rows.
+     * @returns {string} SVG group or an empty string.
+     */
+    static render(symbols) {
+        const markup = (symbols || [])
+            .map((symbol, index) => ({ symbol, index }))
+            .sort(
+                (left, right) =>
+                    CircuitJsonSchematicSheetSymbolSvgRenderer.#order(
+                        left.symbol
+                    ) -
+                        CircuitJsonSchematicSheetSymbolSvgRenderer.#order(
+                            right.symbol
+                        ) || left.index - right.index
+            )
+            .map(({ symbol }) =>
+                CircuitJsonSchematicSheetSymbolSvgRenderer.#symbol(symbol)
+            )
+            .filter(Boolean)
+        return markup.length
+            ? '<g class="schematic-sheet-symbols">' + markup.join('') + '</g>'
+            : ''
+    }
+
+    /**
+     * Renders one child-sheet box and label.
+     * @param {object} symbol Sheet-symbol row.
+     * @returns {string} SVG markup or an empty string.
+     */
+    static #symbol(symbol) {
+        const center = CircuitJsonUnits.optionalPoint(symbol.center)
+        const size = CircuitJsonUnits.optionalSize(symbol)
+        if (!center || !size || size.width <= 0 || size.height <= 0) return ''
+        const sourceFileName = String(symbol.source_file_name || '')
+        return (
+            '<g class="schematic-sheet-symbol" data-schematic-sheet-symbol-id="' +
+            SafeXmlText.escape(symbol.schematic_sheet_symbol_id || '') +
+            '"' +
+            (sourceFileName
+                ? ' data-source-file-name="' +
+                  SafeXmlText.escape(sourceFileName) +
+                  '"'
+                : '') +
+            '><rect class="schematic-sheet-symbol__body" x="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(
+                center.x - size.width / 2
+            ) +
+            '" y="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(
+                center.y - size.height / 2
+            ) +
+            '" width="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(size.width) +
+            '" height="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(size.height) +
+            '"' +
+            CircuitJsonSchematicSvgPrimitiveAttributes.attributes(symbol) +
+            '></rect><text class="schematic-sheet-symbol__label" x="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(center.x) +
+            '" y="' +
+            CircuitJsonSchematicSheetSymbolSvgRenderer.#number(center.y) +
+            '" text-anchor="middle" dominant-baseline="central">' +
+            SafeXmlText.escapeText(symbol.name || '') +
+            '</text></g>'
+        )
+    }
+
+    /**
+     * Resolves one authored render order.
+     * @param {object} symbol Sheet-symbol row.
+     * @returns {number} Sort value.
+     */
+    static #order(symbol) {
+        return Number.isSafeInteger(symbol?.render_order)
+            ? symbol.render_order
+            : Number.MAX_SAFE_INTEGER
+    }
+
+    /**
+     * Formats one deterministic SVG number.
+     * @param {number} value Number value.
+     * @returns {string} SVG number.
+     */
+    static #number(value) {
+        return Number(Number(value).toFixed(6)).toString()
+    }
+}
+
+Object.freeze(CircuitJsonSchematicSheetSymbolSvgRenderer.prototype)
+Object.freeze(CircuitJsonSchematicSheetSymbolSvgRenderer)