altium-toolkit 0.1.0 → 0.1.16

package/src/ui/PcbTextPrimitiveRenderer.mjs

@@ -0,0 +1,252 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+
+/**
+ * Renders recovered PCB text primitives.
+ */
+export class PcbTextPrimitiveRenderer {
+    /**
+     * Selects texts that belong to the requested board-side composite.
+     * @param {{ layerId: number, name: string }[]} primitiveLayers
+     * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, visible?: boolean }[]} texts
+     * @param {'top' | 'bottom'} [side]
+     * @returns {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, visible?: boolean }[]}
+     */
+    static select(primitiveLayers, texts, side = 'top') {
+        const layerIds = PcbTextPrimitiveRenderer.#resolveLayerIds(
+            primitiveLayers || [],
+            side
+        )
+
+        return (texts || []).filter((text) => {
+            const layerId = Number(text?.layerId)
+            return (
+                text?.visible !== false &&
+                String(text?.text || '').trim() &&
+                !PcbTextPrimitiveRenderer.#isPlaceholderText(text) &&
+                Number.isInteger(layerId) &&
+                layerIds.has(layerId)
+            )
+        })
+    }
+
+    /**
+     * Renders selected PCB texts into SVG markup.
+     * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, fontFamily?: string, fontWeight?: number, fontStyle?: string }[]} texts
+     * @returns {string}
+     */
+    static render(texts) {
+        return (texts || [])
+            .map((text) => PcbTextPrimitiveRenderer.#renderText(text))
+            .join('')
+    }
+
+    /**
+     * Renders one PCB text primitive.
+     * @param {{ text: string, x: number, y: number, height?: number, rotation?: number, layerId?: number, fontFamily?: string, fontWeight?: number, fontStyle?: string }} text
+     * @returns {string}
+     */
+    static #renderText(text) {
+        const fontSize = Math.max(Number(text.height || 0), 8)
+        const rotation = Number(text.rotation || 0)
+        const lines = String(text.text || '')
+            .replace(/\r\n?/gu, '\n')
+            .split('\n')
+            .filter((line) => line.length > 0)
+        const content = lines.length
+            ? PcbTextPrimitiveRenderer.#renderTextLines(lines, fontSize)
+            : SchematicSvgUtils.escapeHtml(String(text.text || ''))
+
+        return (
+            '<text class="pcb-text pcb-text--layer-' +
+            SchematicSvgUtils.escapeHtml(String(Number(text.layerId || 0))) +
+            '" transform="translate(' +
+            SchematicSvgUtils.formatNumber(Number(text.x || 0)) +
+            ' ' +
+            SchematicSvgUtils.formatNumber(Number(text.y || 0)) +
+            ') rotate(' +
+            SchematicSvgUtils.formatNumber(rotation) +
+            ')" font-size="' +
+            SchematicSvgUtils.formatNumber(fontSize) +
+            '"' +
+            PcbTextPrimitiveRenderer.#renderFontAttributes(text) +
+            ' text-anchor="start" dominant-baseline="alphabetic">' +
+            content +
+            '</text>'
+        )
+    }
+
+    /**
+     * Renders optional SVG font attributes for TrueType text primitives.
+     * @param {{ fontFamily?: string, fontWeight?: number, fontStyle?: string }} text
+     * @returns {string}
+     */
+    static #renderFontAttributes(text) {
+        let attributes = ''
+
+        if (text.fontFamily && text.fontFamily !== 'Stroke') {
+            attributes +=
+                ' font-family="' +
+                SchematicSvgUtils.escapeHtml(text.fontFamily) +
+                '"'
+        }
+
+        if (text.fontWeight) {
+            attributes +=
+                ' font-weight="' +
+                SchematicSvgUtils.escapeHtml(String(text.fontWeight)) +
+                '"'
+        }
+
+        if (text.fontStyle && text.fontStyle !== 'normal') {
+            attributes +=
+                ' font-style="' +
+                SchematicSvgUtils.escapeHtml(text.fontStyle) +
+                '"'
+        }
+
+        return attributes
+    }
+
+    /**
+     * Renders one or more text lines with SVG tspans.
+     * @param {string[]} lines
+     * @param {number} fontSize
+     * @returns {string}
+     */
+    static #renderTextLines(lines, fontSize) {
+        if (lines.length === 1) {
+            return SchematicSvgUtils.escapeHtml(lines[0])
+        }
+
+        return lines
+            .map(
+                (line, index) =>
+                    '<tspan x="0" dy="' +
+                    SchematicSvgUtils.formatNumber(index === 0 ? 0 : fontSize) +
+                    '">' +
+                    SchematicSvgUtils.escapeHtml(line) +
+                    '</tspan>'
+            )
+            .join('')
+    }
+
+    /**
+     * Resolves candidate text layer ids from layer names, falling back to
+     * standard Altium layer ids when legacy layer metadata is absent.
+     * @param {{ layerId: number, name: string }[]} primitiveLayers
+     * @param {'top' | 'bottom'} side
+     * @returns {Set<number>}
+     */
+    static #resolveLayerIds(primitiveLayers, side) {
+        const matchers = PcbTextPrimitiveRenderer.#resolveLayerMatchers(side)
+        const layerIds = new Set(
+            primitiveLayers
+                .filter((layer) =>
+                    matchers.some((matchesLayerName) =>
+                        matchesLayerName(layer.name)
+                    )
+                )
+                .map((layer) => Number(layer.layerId))
+                .filter((layerId) => Number.isInteger(layerId))
+        )
+
+        if (layerIds.size) {
+            return layerIds
+        }
+
+        return new Set(
+            side === 'bottom' ? [32, 34, 36, 38, 73] : [1, 33, 35, 37, 73]
+        )
+    }
+
+    /**
+     * Resolves side-specific layer-name matchers.
+     * @param {'top' | 'bottom'} side
+     * @returns {((layerName: string) => boolean)[]}
+     */
+    static #resolveLayerMatchers(side) {
+        if (side === 'bottom') {
+            return [
+                (layerName) =>
+                    PcbTextPrimitiveRenderer.#includesLayerName(
+                        layerName,
+                        'BOTTOM OVERLAY'
+                    ),
+                (layerName) =>
+                    PcbTextPrimitiveRenderer.#includesLayerName(
+                        layerName,
+                        'BOTTOM SOLDER'
+                    ),
+                (layerName) =>
+                    PcbTextPrimitiveRenderer.#includesLayerName(
+                        layerName,
+                        'BOTTOM PASTE'
+                    ),
+                (layerName) =>
+                    PcbTextPrimitiveRenderer.#includesLayerName(
+                        layerName,
+                        'L4_BOT'
+                    ),
+                (layerName) =>
+                    PcbTextPrimitiveRenderer.#includesLayerName(
+                        layerName,
+                        'DRILL DRAWING'
+                    )
+            ]
+        }
+
+        return [
+            (layerName) =>
+                PcbTextPrimitiveRenderer.#includesLayerName(
+                    layerName,
+                    'TOP OVERLAY'
+                ),
+            (layerName) =>
+                PcbTextPrimitiveRenderer.#includesLayerName(
+                    layerName,
+                    'TOP SOLDER'
+                ),
+            (layerName) =>
+                PcbTextPrimitiveRenderer.#includesLayerName(
+                    layerName,
+                    'TOP PASTE'
+                ),
+            (layerName) =>
+                PcbTextPrimitiveRenderer.#includesLayerName(
+                    layerName,
+                    'L1_TOP'
+                ),
+            (layerName) =>
+                PcbTextPrimitiveRenderer.#includesLayerName(
+                    layerName,
+                    'DRILL DRAWING'
+                )
+        ]
+    }
+
+    /**
+     * Returns true when a layer name contains the target token.
+     * @param {string} layerName
+     * @param {string} needle
+     * @returns {boolean}
+     */
+    static #includesLayerName(layerName, needle) {
+        return String(layerName || '')
+            .trim()
+            .toUpperCase()
+            .includes(needle)
+    }
+
+    /**
+     * Returns true for unresolved Altium component annotation placeholders.
+     * @param {{ isPlaceholder?: boolean }} text
+     * @returns {boolean}
+     */
+    static #isPlaceholderText(text) {
+        return text?.isPlaceholder === true
+    }
+}

package/src/ui/SchematicSheetChromeRenderer.mjs

@@ -4,6 +4,7 @@
 
 import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
 import { SchematicColorResolver } from './SchematicColorResolver.mjs'
+import { SchematicSheetZoneRenderer } from './SchematicSheetZoneRenderer.mjs'
 
 const {
     basename,
@@ -27,7 +28,7 @@ export class SchematicSheetChromeRenderer {
      */
     static buildMarkup(width, height, sheet, fileName) {
         const margin = Math.max(Number(sheet?.marginWidth || 20), 10)
-        let markup = SchematicSheetChromeRenderer.#buildSheetZoneMarkup(
+        let markup = SchematicSheetZoneRenderer.buildMarkup(
             width,
             height,
             margin,
@@ -915,98 +916,6 @@ export class SchematicSheetChromeRenderer {
         }
     }
 
-    /**
-     * Builds the border zone labels around the sheet frame.
-     * @param {number} width
-     * @param {number} height
-     * @param {number} margin
-     * @param {{ borderOn?: boolean, xZones?: number, yZones?: number }} sheet
-     * @returns {string}
-     */
-    static #buildSheetZoneMarkup(width, height, margin, sheet) {
-        if (!sheet?.borderOn) return ''
-
-        const xZones = Math.max(Number(sheet?.xZones || 0), 1)
-        const yZones = Math.max(Number(sheet?.yZones || 0), 1)
-        const innerWidth = Math.max(width - margin * 2, 10)
-        const innerHeight = Math.max(height - margin * 2, 10)
-        const separator = (x1, y1, x2, y2) =>
-            '<line class="sheet-zone-separator" x1="' +
-            formatNumber(x1) +
-            '" y1="' +
-            formatNumber(y1) +
-            '" x2="' +
-            formatNumber(x2) +
-            '" y2="' +
-            formatNumber(y2) +
-            '" />'
-        let markup = ''
-
-        for (let index = 1; index < xZones; index += 1) {
-            const x = margin + (innerWidth * index) / xZones
-
-            markup +=
-                separator(x, 0, x, margin) +
-                separator(x, height - margin, x, height)
-        }
-
-        for (let index = 0; index < xZones; index += 1) {
-            const label = String(index + 1)
-            const x = margin + (innerWidth * (index + 0.5)) / xZones
-
-            markup +=
-                createSvgText(
-                    'sheet-zone-label',
-                    x,
-                    margin - 6,
-                    label,
-                    'var(--schematic-text-color)',
-                    'middle'
-                ) +
-                createSvgText(
-                    'sheet-zone-label',
-                    x,
-                    height - 4,
-                    label,
-                    'var(--schematic-text-color)',
-                    'middle'
-                )
-        }
-
-        for (let index = 1; index < yZones; index += 1) {
-            const y = margin + (innerHeight * index) / yZones
-
-            markup +=
-                separator(0, y, margin, y) +
-                separator(width - margin, y, width, y)
-        }
-
-        for (let index = 0; index < yZones; index += 1) {
-            const label = String.fromCharCode(65 + index)
-            const y = margin + (innerHeight * (index + 0.5)) / yZones
-
-            markup +=
-                createSvgText(
-                    'sheet-zone-label',
-                    8,
-                    y + 2,
-                    label,
-                    'var(--schematic-text-color)',
-                    'middle'
-                ) +
-                createSvgText(
-                    'sheet-zone-label',
-                    width - 8,
-                    y + 2,
-                    label,
-                    'var(--schematic-text-color)',
-                    'middle'
-                )
-        }
-
-        return markup
-    }
-
     /**
      * Formats the sheet numbering shown in the title block.
      * @param {{ sheetNumber?: string, sheetTotal?: string }} titleBlock

package/src/ui/SchematicSheetZoneRenderer.mjs

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+
+const { createSvgText, formatNumber } = SchematicSvgUtils
+
+/**
+ * Renders schematic border zone labels and separators.
+ */
+export class SchematicSheetZoneRenderer {
+    /**
+     * Builds the border zone labels around the sheet frame.
+     * @param {number} width
+     * @param {number} height
+     * @param {number} margin
+     * @param {{ borderOn?: boolean, xZones?: number, yZones?: number }} sheet
+     * @returns {string}
+     */
+    static buildMarkup(width, height, margin, sheet) {
+        if (!sheet?.borderOn) return ''
+
+        const xZones = Math.max(Number(sheet?.xZones || 0), 1)
+        const yZones = Math.max(Number(sheet?.yZones || 0), 1)
+        const innerWidth = Math.max(width - margin * 2, 10)
+        const innerHeight = Math.max(height - margin * 2, 10)
+        const separator = (x1, y1, x2, y2) =>
+            '<line class="sheet-zone-separator" x1="' +
+            formatNumber(x1) +
+            '" y1="' +
+            formatNumber(y1) +
+            '" x2="' +
+            formatNumber(x2) +
+            '" y2="' +
+            formatNumber(y2) +
+            '" />'
+        let markup = ''
+
+        for (let index = 1; index < xZones; index += 1) {
+            const x = margin + (innerWidth * index) / xZones
+
+            markup +=
+                separator(x, 0, x, margin) +
+                separator(x, height - margin, x, height)
+        }
+
+        for (let index = 0; index < xZones; index += 1) {
+            const label = String(index + 1)
+            const x = margin + (innerWidth * (index + 0.5)) / xZones
+
+            markup +=
+                createSvgText(
+                    'sheet-zone-label',
+                    x,
+                    margin - 6,
+                    label,
+                    'var(--schematic-text-color)',
+                    'middle'
+                ) +
+                createSvgText(
+                    'sheet-zone-label',
+                    x,
+                    height - 4,
+                    label,
+                    'var(--schematic-text-color)',
+                    'middle'
+                )
+        }
+
+        for (let index = 1; index < yZones; index += 1) {
+            const y = margin + (innerHeight * index) / yZones
+
+            markup +=
+                separator(0, y, margin, y) +
+                separator(width - margin, y, width, y)
+        }
+
+        for (let index = 0; index < yZones; index += 1) {
+            const label = String.fromCharCode(65 + index)
+            const y = margin + (innerHeight * (index + 0.5)) / yZones
+
+            markup +=
+                createSvgText(
+                    'sheet-zone-label',
+                    8,
+                    y + 2,
+                    label,
+                    'var(--schematic-text-color)',
+                    'middle'
+                ) +
+                createSvgText(
+                    'sheet-zone-label',
+                    width - 8,
+                    y + 2,
+                    label,
+                    'var(--schematic-text-color)',
+                    'middle'
+                )
+        }
+
+        return markup
+    }
+}