circuitjson-toolkit 1.0.16 → 1.1.0

package/src/ui/BomTableRenderer.mjs

@@ -0,0 +1,304 @@
+import { CircuitJsonDocumentContext } from '../core/context/CircuitJsonDocumentContext.mjs'
+import { CanonicalBomRows } from '../core/rendering/CanonicalBomRows.mjs'
+import { CanonicalBomOrder } from '../core/rendering/CanonicalBomOrder.mjs'
+import { CanonicalRenderOptions } from '../core/rendering/CanonicalRenderOptions.mjs'
+import { SafeXmlText } from './SafeXmlText.mjs'
+
+const PREPARED_BOM_ROWS = new WeakMap()
+const PREPARED_BOM_TABLES = new WeakMap()
+
+/**
+ * Renders canonical grouped BOM data as deterministic HTML.
+ */
+export class BomTableRenderer {
+    /**
+     * Renders a DocumentInput or existing grouped BOM rows.
+     * @param {unknown} document DocumentInput or grouped BOM rows.
+     * @param {Record<string, any>} [options] Canonical render options.
+     * @returns {string} Deterministic BOM HTML.
+     */
+    static render(document, options = {}) {
+        const normalized = CanonicalRenderOptions.normalize(options)
+        CanonicalRenderOptions.requireCanonicalFidelity(normalized.fidelity)
+        const legacyRows = BomTableRenderer.#legacyRows(document)
+        if (legacyRows) {
+            return BomTableRenderer.#renderRows(legacyRows)
+        }
+        const context = CircuitJsonDocumentContext.prepare(document)
+        const rows = context.getOrCreateDerived('render', 'bom-rows-v1', () => {
+            const built = CanonicalBomRows.build(context.model)
+            BomTableRenderer.#freeze(built)
+            PREPARED_BOM_ROWS.set(built, context)
+            return built
+        })
+        if (!Array.isArray(rows) || PREPARED_BOM_ROWS.get(rows) !== context) {
+            throw CanonicalRenderOptions.error(
+                'BOM rendering encountered a derived-row cache collision.'
+            )
+        }
+        const table = context.getOrCreateDerived(
+            'render',
+            'bom-table-v1',
+            () => {
+                const entry = Object.freeze({
+                    html: BomTableRenderer.#renderRows(rows)
+                })
+                PREPARED_BOM_TABLES.set(entry, context)
+                return entry
+            }
+        )
+        if (
+            !table ||
+            typeof table !== 'object' ||
+            PREPARED_BOM_TABLES.get(table) !== context
+        ) {
+            throw CanonicalRenderOptions.error(
+                'BOM rendering encountered a derived-table cache collision.'
+            )
+        }
+        return table.html
+    }
+
+    /**
+     * Copies a legacy grouped-row input through safe own data descriptors.
+     * @param {unknown} value Input candidate.
+     * @returns {object[] | null} Safe grouped rows or null for DocumentInput.
+     */
+    static #legacyRows(value) {
+        const entries = BomTableRenderer.#arrayEntries(value)
+        if (!entries?.length) return null
+        const descriptors = entries.map((row) =>
+            BomTableRenderer.#rowDescriptors(row)
+        )
+        if (descriptors.some((row) => row?.type)) return null
+        if (descriptors.some((row) => !row)) return null
+        return descriptors
+            .map((row) => BomTableRenderer.#copyRow(row))
+            .sort(CanonicalBomOrder.compareRows)
+    }
+
+    /**
+     * Copies top-level array entries through own data descriptors.
+     * @param {unknown} value Array candidate.
+     * @returns {unknown[] | null} Safe entries or null.
+     */
+    static #arrayEntries(value) {
+        let isArray
+        let descriptors
+        try {
+            isArray = Array.isArray(value)
+            if (!isArray || Object.getPrototypeOf(value) !== Array.prototype) {
+                return null
+            }
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            return null
+        }
+        const length = descriptors.length?.value
+        if (!Number.isSafeInteger(length) || length < 0 || length > 1000000) {
+            return null
+        }
+        const result = []
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = descriptors[String(index)]
+            if (!descriptor || descriptor.get || descriptor.set) {
+                throw CanonicalRenderOptions.error(
+                    'BOM input arrays must contain only plain data entries.'
+                )
+            }
+            result.push(descriptor.value)
+        }
+        return result
+    }
+
+    /**
+     * Inspects one possible legacy row without reading its fields.
+     * @param {unknown} row Row candidate.
+     * @returns {Record<string, PropertyDescriptor> | null} Descriptors or null.
+     */
+    static #rowDescriptors(row) {
+        if (!row || typeof row !== 'object' || Array.isArray(row)) return null
+        try {
+            const prototype = Object.getPrototypeOf(row)
+            if (prototype !== Object.prototype && prototype !== null)
+                return null
+            return Object.getOwnPropertyDescriptors(row)
+        } catch {
+            return null
+        }
+    }
+
+    /**
+     * Copies and validates one legacy grouped BOM row.
+     * @param {Record<string, PropertyDescriptor>} descriptors Row descriptors.
+     * @returns {object} Safe grouped row.
+     */
+    static #copyRow(descriptors) {
+        for (const descriptor of Object.values(descriptors)) {
+            if (descriptor.get || descriptor.set) {
+                throw CanonicalRenderOptions.error(
+                    'BOM rows must contain only plain data fields.'
+                )
+            }
+        }
+        const designators = BomTableRenderer.#stringArray(
+            descriptors.designators?.value
+        )
+        if (!designators?.length) {
+            throw CanonicalRenderOptions.error(
+                'BOM rows require a non-empty designators array.'
+            )
+        }
+        const quantity = descriptors.quantity?.value
+        if (
+            quantity !== undefined &&
+            (!Number.isSafeInteger(quantity) || quantity < 0)
+        ) {
+            throw CanonicalRenderOptions.error(
+                'BOM row quantity must be a nonnegative integer.'
+            )
+        }
+        return {
+            designators: [...new Set(designators)].sort(
+                CanonicalBomOrder.compareDesignators
+            ),
+            quantity: quantity ?? designators.length,
+            value: BomTableRenderer.#scalar(descriptors.value?.value),
+            pattern: BomTableRenderer.#scalar(descriptors.pattern?.value),
+            source: BomTableRenderer.#scalar(descriptors.source?.value)
+        }
+    }
+
+    /**
+     * Copies a dense plain string array without indexed property reads.
+     * @param {unknown} value Array candidate.
+     * @returns {string[] | null} Safe string array.
+     */
+    static #stringArray(value) {
+        let descriptors
+        try {
+            if (!Array.isArray(value)) return null
+            if (Object.getPrototypeOf(value) !== Array.prototype) return null
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            return null
+        }
+        const length = descriptors.length?.value
+        if (!Number.isSafeInteger(length) || length < 1 || length > 4096) {
+            return null
+        }
+        const result = []
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = descriptors[String(index)]
+            if (
+                !descriptor ||
+                descriptor.get ||
+                descriptor.set ||
+                typeof descriptor.value !== 'string' ||
+                !descriptor.value.trim()
+            ) {
+                return null
+            }
+            result.push(descriptor.value.trim())
+        }
+        return result
+    }
+
+    /**
+     * Normalizes an optional primitive BOM display value.
+     * @param {unknown} value Value candidate.
+     * @returns {string | number | boolean} Safe scalar.
+     */
+    static #scalar(value) {
+        if (value === undefined || value === null) return ''
+        if (!['string', 'number', 'boolean'].includes(typeof value)) {
+            throw CanonicalRenderOptions.error(
+                'BOM row display fields must be scalar values.'
+            )
+        }
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw CanonicalRenderOptions.error(
+                'BOM row display fields must be finite.'
+            )
+        }
+        return value
+    }
+
+    /**
+     * Iteratively freezes renderer-owned BOM rows without recursion limits.
+     * @param {unknown} value Renderer-owned value.
+     * @returns {unknown} Frozen value.
+     */
+    static #freeze(value) {
+        const pending = [value]
+        const visited = new WeakSet()
+        while (pending.length) {
+            const current = pending.pop()
+            if (
+                !current ||
+                typeof current !== 'object' ||
+                visited.has(current)
+            ) {
+                continue
+            }
+            visited.add(current)
+            for (const descriptor of Object.values(
+                Object.getOwnPropertyDescriptors(current)
+            )) {
+                if ('value' in descriptor) pending.push(descriptor.value)
+            }
+            Object.freeze(current)
+        }
+        return value
+    }
+
+    /**
+     * Renders normalized grouped rows.
+     * @param {object[]} rows Grouped BOM rows.
+     * @returns {string} Deterministic BOM HTML.
+     */
+    static #renderRows(rows) {
+        if (!rows.length) {
+            return '<section class="bom-empty">No BOM rows recovered.</section>'
+        }
+        return (
+            '<table class="bom-table"><thead><tr>' +
+            '<th>Designators</th><th>Qty</th><th>Value</th><th>Pattern</th><th>Source</th>' +
+            '</tr></thead><tbody>' +
+            rows.map((row) => BomTableRenderer.#renderRow(row)).join('') +
+            '</tbody></table>'
+        )
+    }
+
+    /**
+     * Renders one escaped BOM row.
+     * @param {object} row Grouped BOM row.
+     * @returns {string} Table row HTML.
+     */
+    static #renderRow(row) {
+        return (
+            '<tr><td>' +
+            BomTableRenderer.#escape((row.designators || []).join(', ')) +
+            '</td><td>' +
+            BomTableRenderer.#escape(
+                row.quantity ?? row.designators?.length ?? 0
+            ) +
+            '</td><td>' +
+            BomTableRenderer.#escape(row.value ?? '') +
+            '</td><td>' +
+            BomTableRenderer.#escape(row.pattern ?? '') +
+            '</td><td>' +
+            BomTableRenderer.#escape(row.source ?? '') +
+            '</td></tr>'
+        )
+    }
+
+    /**
+     * Escapes HTML text.
+     * @param {unknown} value Raw value.
+     * @returns {string} Escaped text.
+     */
+    static #escape(value) {
+        return SafeXmlText.escape(value)
+    }
+}

package/src/ui/CircuitJsonPcbBoardSvgRenderer.mjs

@@ -0,0 +1,80 @@
+import { SafeXmlText } from './SafeXmlText.mjs'
+
+/**
+ * Serializes every prepared PCB board substrate in stable primitive order.
+ */
+export class CircuitJsonPcbBoardSvgRenderer {
+    /**
+     * Renders all board primitives in one prepared primitive model.
+     * @param {{ primitives?: object[] }} model Primitive model.
+     * @returns {string} Board substrate markup.
+     */
+    static render(model) {
+        const markup = []
+        for (const board of model.primitives || []) {
+            if (board.kind !== 'board' || !board.bounds) continue
+            markup.push(CircuitJsonPcbBoardSvgRenderer.#renderBoard(board))
+        }
+        return markup.join('')
+    }
+
+    /**
+     * Renders one polygonal or rectangular board primitive.
+     * @param {object} board Board primitive.
+     * @returns {string} Board markup.
+     */
+    static #renderBoard(board) {
+        if (Array.isArray(board.points) && board.points.length >= 3) {
+            return (
+                '<polygon class="pcb-board" data-layer="board" points="' +
+                SafeXmlText.escape(
+                    CircuitJsonPcbBoardSvgRenderer.#points(board.points)
+                ) +
+                '"></polygon>'
+            )
+        }
+        return (
+            '<rect class="pcb-board" x="' +
+            CircuitJsonPcbBoardSvgRenderer.#number(board.bounds.minX) +
+            '" y="' +
+            CircuitJsonPcbBoardSvgRenderer.#number(board.bounds.minY) +
+            '" width="' +
+            CircuitJsonPcbBoardSvgRenderer.#number(board.bounds.width) +
+            '" height="' +
+            CircuitJsonPcbBoardSvgRenderer.#number(board.bounds.height) +
+            '" rx="' +
+            CircuitJsonPcbBoardSvgRenderer.#number(
+                Math.min(board.bounds.width, board.bounds.height) * 0.018
+            ) +
+            '" data-layer="board"></rect>'
+        )
+    }
+
+    /**
+     * Formats polygon points for an SVG attribute.
+     * @param {{ x: number, y: number }[]} points Polygon points.
+     * @returns {string} SVG point list.
+     */
+    static #points(points) {
+        return points
+            .map(
+                (point) =>
+                    CircuitJsonPcbBoardSvgRenderer.#number(point.x) +
+                    ',' +
+                    CircuitJsonPcbBoardSvgRenderer.#number(point.y)
+            )
+            .join(' ')
+    }
+
+    /**
+     * 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/CircuitJsonPcbPrimitiveAttributeRenderer.mjs

@@ -1,3 +1,5 @@
+import { SafeXmlText } from './SafeXmlText.mjs'
+
 /**
  * Renders shared SVG attributes for CircuitJSON PCB primitives.
  */
@@ -119,10 +121,6 @@ export class CircuitJsonPcbPrimitiveAttributeRenderer {
      * @returns {string}
      */
     static #escapeHtml(value) {
-        return String(value ?? '')
-            .replaceAll('&', '&')
-            .replaceAll('<', '&lt;')
-            .replaceAll('>', '&gt;')
-            .replaceAll('"', '&quot;')
+        return SafeXmlText.escape(value)
     }
 }

package/src/ui/CircuitJsonPcbSvgRenderer.mjs

@@ -1,6 +1,10 @@
 import { PcbInteractionPrimitiveModel } from '../core/PcbInteractionPrimitiveModel.mjs'
+import { PcbRenderPlan } from '../core/rendering/PcbRenderPlan.mjs'
+import { CanonicalSvgDocument } from '../core/rendering/CanonicalSvgDocument.mjs'
+import { CircuitJsonPcbBoardSvgRenderer } from './CircuitJsonPcbBoardSvgRenderer.mjs'
 import { CircuitJsonPcbPrimitiveAttributeRenderer } from './CircuitJsonPcbPrimitiveAttributeRenderer.mjs'
 import { CircuitJsonPcbViaSvgRenderer } from './CircuitJsonPcbViaSvgRenderer.mjs'
+import { SafeXmlText } from './SafeXmlText.mjs'
 /**
  * Renders standards-shaped PCB element arrays into app-compatible SVG.
  */
@@ -14,6 +18,54 @@ export class CircuitJsonPcbSvgRenderer {
     static render(documentModel, options = {}) {
         const side = options.side === 'bottom' ? 'bottom' : 'top'
         const model = PcbInteractionPrimitiveModel.build(documentModel)
+        return CircuitJsonPcbSvgRenderer.#renderModel(model, side)
+    }
+
+    /**
+     * Renders multiple board sides from one prepared primitive model.
+     * @param {object | object[]} documentModel Parsed document model.
+     * @param {unknown[]} [sides] Requested board sides.
+     * @returns {string[]} SVG markup in requested order.
+     */
+    static renderSides(documentModel, sides = ['top', 'bottom']) {
+        const model = PcbInteractionPrimitiveModel.build(documentModel)
+        const requested = Array.isArray(sides) ? sides : [sides]
+        return requested.map((side) =>
+            CircuitJsonPcbSvgRenderer.#renderModel(
+                model,
+                side === 'bottom' ? 'bottom' : 'top'
+            )
+        )
+    }
+
+    /**
+     * Renders one prepared PCB plan without rebuilding primitives.
+     * @param {Record<string, any>} plan Prepared PCB render plan.
+     * @param {{ layerIds?: string[] | null }} [options] Prepared-plan options.
+     * @returns {string} SVG markup.
+     */
+    static renderPlan(plan, options = {}) {
+        PcbRenderPlan.requirePrepared(plan)
+        const layerIds =
+            options.layerIds === undefined
+                ? plan.selectedLayerIds
+                : options.layerIds
+        return CanonicalSvgDocument.decorate(
+            CircuitJsonPcbSvgRenderer.#renderModel(
+                PcbRenderPlan.modelForLayers(plan, layerIds),
+                plan.side
+            ),
+            plan.svg
+        )
+    }
+
+    /**
+     * Wraps one prepared primitive model in the stable SVG document.
+     * @param {Record<string, any>} model Prepared primitive model.
+     * @param {'top' | 'bottom'} side Active side.
+     * @returns {string} SVG markup.
+     */
+    static #renderModel(model, side) {
         const viewBox = CircuitJsonPcbSvgRenderer.#viewBox(model.bounds)
         return (
             '<svg class="pcb-svg pcb-svg--app-palette pcb-svg--circuitjson pcb-svg--' +
@@ -21,48 +73,13 @@ export class CircuitJsonPcbSvgRenderer {
             '" xmlns="http://www.w3.org/2000/svg" role="img" viewBox="' +
             CircuitJsonPcbSvgRenderer.#formatViewBox(viewBox) +
             '">' +
-            CircuitJsonPcbSvgRenderer.#renderBoard(model) +
+            CircuitJsonPcbBoardSvgRenderer.render(model) +
             CircuitJsonPcbSvgRenderer.#renderCopper(model, side) +
             CircuitJsonPcbSvgRenderer.#renderComponentLabels(model) +
             CircuitJsonPcbSvgRenderer.#renderOverlays(model, side) +
             '</svg>'
         )
     }
-    /**
-     * Renders the board substrate.
-     * @param {{ primitives: object[] }} model Primitive model.
-     * @returns {string}
-     */
-    static #renderBoard(model) {
-        const board = model.primitives.find(
-            (primitive) => primitive.kind === 'board'
-        )
-        if (!board?.bounds) return ''
-        if (Array.isArray(board.points) && board.points.length >= 3) {
-            return (
-                '<polygon class="pcb-board" data-layer="board" points="' +
-                CircuitJsonPcbSvgRenderer.#escapeHtml(
-                    CircuitJsonPcbSvgRenderer.#pointsAttribute(board.points)
-                ) +
-                '"></polygon>'
-            )
-        }
-        return (
-            '<rect class="pcb-board" x="' +
-            CircuitJsonPcbSvgRenderer.#formatNumber(board.bounds.minX) +
-            '" y="' +
-            CircuitJsonPcbSvgRenderer.#formatNumber(board.bounds.minY) +
-            '" width="' +
-            CircuitJsonPcbSvgRenderer.#formatNumber(board.bounds.width) +
-            '" height="' +
-            CircuitJsonPcbSvgRenderer.#formatNumber(board.bounds.height) +
-            '" rx="' +
-            CircuitJsonPcbSvgRenderer.#formatNumber(
-                Math.min(board.bounds.width, board.bounds.height) * 0.018
-            ) +
-            '" data-layer="board"></rect>'
-        )
-    }
     /**
      * Renders copper and drilled primitives.
      * @param {{ primitives: object[] }} model Primitive model.
@@ -755,9 +772,16 @@ export class CircuitJsonPcbSvgRenderer {
         if (primitiveSide) return primitiveSide === side
 
         const layer = String(primitive.layer || '').toLowerCase()
-        if (side === 'bottom') return layer === 'bottom'
+        if (side === 'bottom') {
+            return layer === 'bottom' || layer.startsWith('bottom_')
+        }
 
-        return layer === 'top' || !layer || layer === 'board'
+        return (
+            layer === 'top' ||
+            layer.startsWith('top_') ||
+            !layer ||
+            layer === 'board'
+        )
     }
 
     /**
@@ -955,10 +979,6 @@ export class CircuitJsonPcbSvgRenderer {
      * @returns {string}
      */
     static #escapeHtml(value) {
-        return String(value ?? '')
-            .replaceAll('&', '&amp;')
-            .replaceAll('<', '&lt;')
-            .replaceAll('>', '&gt;')
-            .replaceAll('"', '&quot;')
+        return SafeXmlText.escape(value)
     }
 }

package/src/ui/CircuitJsonPcbViaSvgRenderer.mjs

@@ -1,3 +1,5 @@
+import { SafeXmlText } from './SafeXmlText.mjs'
+
 /**
  * Renders via-like drilled primitives as SVG shapes.
  */
@@ -159,10 +161,6 @@ export class CircuitJsonPcbViaSvgRenderer {
      * @returns {string}
      */
     static #escapeHtml(value) {
-        return String(value ?? '')
-            .replaceAll('&', '&')
-            .replaceAll('"', '"')
-            .replaceAll('<', '&lt;')
-            .replaceAll('>', '&gt;')
+        return SafeXmlText.escape(value)
     }
 }