altium-toolkit 0.1.0

package/src/ui/SchematicNoteRenderer.mjs

@@ -0,0 +1,427 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { SchematicSvgUtils } from './SchematicSvgUtils.mjs'
+import { SchematicColorResolver } from './SchematicColorResolver.mjs'
+import { SchematicTypography } from './SchematicTypography.mjs'
+
+const { escapeHtml, formatNumber, projectSchematicY } = SchematicSvgUtils
+const MINIMUM_NOTE_TEXT_SIZE = 4
+
+/**
+ * Renders boxed schematic notes recovered from Altium note records.
+ */
+export class SchematicNoteRenderer {
+    /**
+     * Builds one boxed schematic note/callout with wrapped text rows.
+     * @param {{ x: number, y: number, color: string, fontSize?: number, fontFamily?: string, fontWeight?: number, cornerX?: number, cornerY?: number, fill?: string, borderColor?: string, isSolid?: boolean, showBorder?: boolean, textMargin?: number, noteLines?: string[] }} text
+     * @param {number} sheetHeight
+     * @returns {string}
+     */
+    static buildMarkup(text, sheetHeight) {
+        const left = Math.min(text.x, text.cornerX || text.x)
+        const right = Math.max(text.x, text.cornerX || text.x)
+        const top = Math.min(
+            projectSchematicY(sheetHeight, text.y),
+            projectSchematicY(sheetHeight, text.cornerY || text.y)
+        )
+        const bottom = Math.max(
+            projectSchematicY(sheetHeight, text.y),
+            projectSchematicY(sheetHeight, text.cornerY || text.y)
+        )
+        const width = Math.max(right - left, 1)
+        const height = Math.max(bottom - top, 1)
+        const textMargin = Math.max(Number(text.textMargin || 4), 3)
+        const requestedTextSize = Math.max(
+            Number(
+                SchematicTypography.resolveViewerFontSize(text.fontSize || 8) ||
+                    MINIMUM_NOTE_TEXT_SIZE
+            ),
+            MINIMUM_NOTE_TEXT_SIZE
+        )
+        const noteFill = SchematicColorResolver.resolveFill(
+            text.isSolid === false
+                ? 'transparent'
+                : text.fill || 'var(--schematic-note-fill-color)',
+            '--schematic-note-fill-color'
+        )
+        const borderColor = SchematicColorResolver.resolveColor(
+            text.borderColor || 'var(--schematic-note-border-color)',
+            '--schematic-note-border-color'
+        )
+        const noteStroke = text.showBorder ? borderColor : 'none'
+        const layout = SchematicNoteRenderer.#resolveTextLayout(
+            text.noteLines || [],
+            Math.max(width - textMargin * 2, requestedTextSize),
+            Math.max(height - textMargin * 2, requestedTextSize),
+            requestedTextSize
+        )
+        const noteLines = layout.noteLines
+        const textSize = layout.textSize
+        const lineHeight = layout.lineHeight
+        const textMarkup = noteLines
+            .map((line, index) =>
+                SchematicNoteRenderer.#buildNoteLineMarkup(
+                    line,
+                    index,
+                    left,
+                    right,
+                    top,
+                    textMargin,
+                    lineHeight,
+                    textSize,
+                    text
+                )
+            )
+            .join('')
+
+        return (
+            '<g class="schematic-note">' +
+            '<rect class="schematic-note-box" x="' +
+            formatNumber(left) +
+            '" y="' +
+            formatNumber(top) +
+            '" width="' +
+            formatNumber(width) +
+            '" height="' +
+            formatNumber(height) +
+            '" fill="' +
+            escapeHtml(noteFill) +
+            '" stroke="' +
+            escapeHtml(noteStroke) +
+            '" />' +
+            textMarkup +
+            '</g>'
+        )
+    }
+
+    /**
+     * Resolves wrapped note rows and a fitting text layout for one note box.
+     * @param {string[]} noteLines
+     * @param {number} maxWidth
+     * @param {number} maxHeight
+     * @param {number} requestedTextSize
+     * @returns {{ noteLines: string[], textSize: number, lineHeight: number }}
+     */
+    static #resolveTextLayout(
+        noteLines,
+        maxWidth,
+        maxHeight,
+        requestedTextSize
+    ) {
+        let textSize = requestedTextSize
+        let wrappedLines = []
+
+        for (let attempt = 0; attempt < 6; attempt += 1) {
+            wrappedLines = SchematicNoteRenderer.#wrapNoteLines(
+                noteLines,
+                maxWidth,
+                textSize
+            )
+
+            const lineHeight = SchematicNoteRenderer.#resolveLineHeight(
+                textSize,
+                maxHeight,
+                0,
+                wrappedLines.length
+            )
+            const requiredHeight =
+                wrappedLines.length <= 0
+                    ? 0
+                    : textSize + lineHeight * (wrappedLines.length - 1)
+
+            if (
+                requiredHeight <= maxHeight ||
+                textSize <= MINIMUM_NOTE_TEXT_SIZE
+            ) {
+                return {
+                    noteLines: wrappedLines,
+                    textSize,
+                    lineHeight
+                }
+            }
+
+            const nextSize = Math.max(
+                MINIMUM_NOTE_TEXT_SIZE,
+                Math.min(
+                    textSize - 0.5,
+                    textSize * (maxHeight / requiredHeight)
+                )
+            )
+
+            if (nextSize >= textSize) {
+                break
+            }
+
+            textSize = nextSize
+        }
+
+        return {
+            noteLines: wrappedLines,
+            textSize,
+            lineHeight: SchematicNoteRenderer.#resolveLineHeight(
+                textSize,
+                maxHeight,
+                0,
+                wrappedLines.length
+            )
+        }
+    }
+
+    /**
+     * Wraps recovered note rows to the available note-box width.
+     * @param {string[]} noteLines
+     * @param {number} maxWidth
+     * @param {number} textSize
+     * @returns {string[]}
+     */
+    static #wrapNoteLines(noteLines, maxWidth, textSize) {
+        return noteLines.flatMap((line) =>
+            SchematicNoteRenderer.#wrapSingleLine(line, maxWidth, textSize)
+        )
+    }
+
+    /**
+     * Wraps one visible note row to the available width.
+     * @param {string} line
+     * @param {number} maxWidth
+     * @param {number} textSize
+     * @returns {string[]}
+     */
+    static #wrapSingleLine(line, maxWidth, textSize) {
+        const normalizedLine = String(line || '').trim()
+        if (!normalizedLine) {
+            return []
+        }
+
+        if (/^_+$/.test(normalizedLine)) {
+            return [normalizedLine]
+        }
+
+        if (
+            SchematicNoteRenderer.#estimateTextWidth(
+                normalizedLine,
+                textSize
+            ) <= maxWidth
+        ) {
+            return [normalizedLine]
+        }
+
+        const wrappedLines = []
+        let currentLine = ''
+        const tokens = normalizedLine.match(/\S+\s*/g) || [normalizedLine]
+
+        for (const token of tokens) {
+            const trimmedToken = token.trim()
+            if (!trimmedToken) {
+                continue
+            }
+
+            const candidateLine = (currentLine + token).trimEnd()
+            if (
+                currentLine &&
+                SchematicNoteRenderer.#estimateTextWidth(
+                    candidateLine,
+                    textSize
+                ) > maxWidth
+            ) {
+                wrappedLines.push(currentLine.trimEnd())
+                currentLine = ''
+            }
+
+            if (
+                SchematicNoteRenderer.#estimateTextWidth(
+                    trimmedToken,
+                    textSize
+                ) > maxWidth
+            ) {
+                const tokenLines = SchematicNoteRenderer.#wrapLongToken(
+                    trimmedToken,
+                    maxWidth,
+                    textSize
+                )
+
+                if (currentLine) {
+                    wrappedLines.push(currentLine.trimEnd())
+                    currentLine = ''
+                }
+
+                wrappedLines.push(...tokenLines.slice(0, -1))
+                currentLine = tokenLines[tokenLines.length - 1] || ''
+                continue
+            }
+
+            currentLine = (currentLine + token).trimStart()
+        }
+
+        if (currentLine) {
+            wrappedLines.push(currentLine.trimEnd())
+        }
+
+        return wrappedLines
+    }
+
+    /**
+     * Splits one oversized token into smaller width-safe fragments.
+     * @param {string} token
+     * @param {number} maxWidth
+     * @param {number} textSize
+     * @returns {string[]}
+     */
+    static #wrapLongToken(token, maxWidth, textSize) {
+        const fragments = []
+        let currentFragment = ''
+
+        for (const character of token) {
+            const candidateFragment = currentFragment + character
+            if (
+                currentFragment &&
+                SchematicNoteRenderer.#estimateTextWidth(
+                    candidateFragment,
+                    textSize
+                ) > maxWidth
+            ) {
+                fragments.push(currentFragment)
+                currentFragment = character
+                continue
+            }
+
+            currentFragment = candidateFragment
+        }
+
+        if (currentFragment) {
+            fragments.push(currentFragment)
+        }
+
+        return fragments
+    }
+
+    /**
+     * Approximates rendered note text width for line wrapping.
+     * @param {string} text
+     * @param {number} textSize
+     * @returns {number}
+     */
+    static #estimateTextWidth(text, textSize) {
+        let width = 0
+
+        for (const character of String(text || '')) {
+            width +=
+                SchematicNoteRenderer.#measureCharacterWidth(character) *
+                textSize
+        }
+
+        return width
+    }
+
+    /**
+     * Returns a rough Times New Roman width factor for one character.
+     * @param {string} character
+     * @returns {number}
+     */
+    static #measureCharacterWidth(character) {
+        if (/\s/.test(character)) return 0.32
+        if (/[.,;:!|]/.test(character)) return 0.24
+        if (/[()[\]{}]/.test(character)) return 0.32
+        if (/[-+/\\]/.test(character)) return 0.36
+        if (/[MW@#%&]/.test(character)) return 0.82
+        if (/[A-Z]/.test(character)) return 0.62
+        if (/[a-z0-9]/.test(character)) return 0.5
+        if (/[^ -~]/.test(character)) return 0.92
+
+        return 0.56
+    }
+
+    /**
+     * Picks a readable line height that still fits inside the note box.
+     * @param {number} textSize
+     * @param {number} noteHeight
+     * @param {number} textMargin
+     * @param {number} lineCount
+     * @returns {number}
+     */
+    static #resolveLineHeight(textSize, noteHeight, textMargin, lineCount) {
+        const defaultLineHeight = Math.max(textSize * 1.1, textSize + 1)
+        if (lineCount <= 1) {
+            return defaultLineHeight
+        }
+
+        const maxLineHeight =
+            (noteHeight - textMargin * 2 - textSize) / (lineCount - 1)
+
+        return Math.max(Math.min(defaultLineHeight, maxLineHeight), textSize)
+    }
+
+    /**
+     * Builds one rendered line inside a schematic note box.
+     * @param {string} line
+     * @param {number} index
+     * @param {number} left
+     * @param {number} right
+     * @param {number} top
+     * @param {number} textMargin
+     * @param {number} lineHeight
+     * @param {number} textSize
+     * @param {{ color: string, fontFamily?: string, fontWeight?: number }} text
+     * @returns {string}
+     */
+    static #buildNoteLineMarkup(
+        line,
+        index,
+        left,
+        right,
+        top,
+        textMargin,
+        lineHeight,
+        textSize,
+        text
+    ) {
+        const x = left + textMargin
+        const y = top + textMargin + textSize + index * lineHeight
+
+        if (/^_+$/.test(String(line || '').trim())) {
+            return (
+                '<line class="schematic-note-rule" x1="' +
+                formatNumber(x) +
+                '" y1="' +
+                formatNumber(y - textSize * 0.35) +
+                '" x2="' +
+                formatNumber(right - textMargin) +
+                '" y2="' +
+                formatNumber(y - textSize * 0.35) +
+                '" stroke="' +
+                escapeHtml(
+                    SchematicColorResolver.resolveColor(
+                        text.color,
+                        '--schematic-text-color'
+                    )
+                ) +
+                '" />'
+            )
+        }
+
+        return (
+            '<text class="schematic-note-text" x="' +
+            formatNumber(x) +
+            '" y="' +
+            formatNumber(y) +
+            '" fill="' +
+            escapeHtml(
+                SchematicColorResolver.resolveColor(
+                    text.color,
+                    '--schematic-text-color'
+                )
+            ) +
+            '" text-anchor="start" font-size="' +
+            formatNumber(textSize) +
+            '" font-family="' +
+            escapeHtml(text.fontFamily || 'Times New Roman') +
+            '" font-weight="' +
+            formatNumber(text.fontWeight || 400) +
+            '" xml:space="preserve">' +
+            escapeHtml(line) +
+            '</text>'
+        )
+    }
+}

package/src/ui/SchematicOwnerPinLabelLayout.mjs

@@ -0,0 +1,173 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Shared layout helpers for explicit owner pin-name labels and their paired
+ * synthetic pin-number clearance.
+ */
+export class SchematicOwnerPinLabelLayout {
+    /**
+     * Builds one owner/pin label key.
+     * @param {string | undefined} ownerIndex
+     * @param {string | undefined} name
+     * @returns {string}
+     */
+    static buildOwnerPinLabelKey(ownerIndex, name) {
+        const normalizedOwnerIndex = String(ownerIndex || '').trim()
+        const normalizedName = String(name || '').trim()
+
+        if (!normalizedOwnerIndex || !normalizedName) {
+            return ''
+        }
+
+        return normalizedOwnerIndex + '::' + normalizedName
+    }
+
+    /**
+     * Returns one matched owner pin when a free text primitive is explicitly
+     * reusing that pin name.
+     * @param {{ text?: string, ownerIndex?: string }} text
+     * @param {{ x: number, y: number, name?: string, ownerIndex?: string, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
+     * @returns {{ x: number, y: number, name?: string, ownerIndex?: string, orientation: 'left' | 'right' | 'top' | 'bottom' } | null}
+     */
+    static findExplicitOwnerPinLabelMatch(text, pins) {
+        const ownerIndex = String(text?.ownerIndex || '').trim()
+        const label = String(text?.text || '').trim()
+
+        if (!ownerIndex || !label) {
+            return null
+        }
+
+        return (
+            pins.find(
+                (pin) =>
+                    String(pin.ownerIndex || '').trim() === ownerIndex &&
+                    String(pin.name || '').trim() === label
+            ) || null
+        )
+    }
+
+    /**
+     * Reuses the matched pin axis for mirrored vertical owner pin-name labels
+     * while keeping their authored run distance along that axis.
+     * @param {{ x: number, y: number, recordType?: string, rotation?: number, isMirrored?: boolean }} text
+     * @param {{ x: number, y: number, name?: string, ownerIndex?: string, orientation: 'left' | 'right' | 'top' | 'bottom' } | null} matchedOwnerPin
+     * @returns {{ x: number, y: number } | null}
+     */
+    static resolveMirroredOwnerPinLabelPlacement(text, matchedOwnerPin) {
+        if (
+            !matchedOwnerPin ||
+            !text?.isMirrored ||
+            !text?.rotation ||
+            text.recordType !== '4'
+        ) {
+            return null
+        }
+
+        return {
+            x: Number(matchedOwnerPin.x),
+            y: Number(text.y)
+        }
+    }
+
+    /**
+     * Collects the horizontal correction applied to explicit owner pin-name
+     * labels so synthetic left/right pin numbers can keep their original gap.
+     * @param {{ ownerIndex?: string, text?: string, x?: number, y?: number, recordType?: string, rotation?: number, isMirrored?: boolean }[]} texts
+     * @param {{ x: number, y: number, name?: string, ownerIndex?: string, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
+     * @returns {Map<string, number>}
+     */
+    static collectExplicitOwnerPinLabelOffsets(texts, pins) {
+        const offsets = new Map()
+
+        for (const text of texts) {
+            const matchedOwnerPin =
+                SchematicOwnerPinLabelLayout.findExplicitOwnerPinLabelMatch(
+                    text,
+                    pins
+                )
+            const placement =
+                SchematicOwnerPinLabelLayout.resolveMirroredOwnerPinLabelPlacement(
+                    text,
+                    matchedOwnerPin
+                )
+            const key = SchematicOwnerPinLabelLayout.buildOwnerPinLabelKey(
+                text?.ownerIndex,
+                text?.text
+            )
+
+            if (!placement || !key) {
+                continue
+            }
+
+            const delta = Number(placement.x) - Number(text.x)
+
+            if (delta) {
+                offsets.set(key, delta)
+            }
+        }
+
+        return offsets
+    }
+
+    /**
+     * Resolves the final SVG text anchor for one schematic free-text label.
+     * Mirrored rotated owner pin-name labels need the opposite text edge so
+     * their baseline starts on the same visual side after the signed rotation
+     * flips.
+     * @param {{ recordType?: string, rotation?: number, isMirrored?: boolean, y?: number }} text
+     * @param {'start' | 'middle' | 'end'} anchor
+     * @param {{ y: number, name?: string, ownerIndex?: string, orientation: 'left' | 'right' | 'top' | 'bottom' } | null} matchedOwnerPin
+     * @returns {'start' | 'middle' | 'end'}
+     */
+    static resolveSchematicTextAnchor(text, anchor, matchedOwnerPin) {
+        if (
+            anchor !== 'start' ||
+            !text?.isMirrored ||
+            !text?.rotation ||
+            text.recordType !== '4'
+        ) {
+            return anchor
+        }
+
+        if (!matchedOwnerPin) {
+            return anchor
+        }
+
+        return Number(text.y) >= Number(matchedOwnerPin.y) ? 'end' : 'start'
+    }
+
+    /**
+     * Moves left/right pin numbers outward by the same horizontal correction
+     * already applied to their explicit owner pin-name labels.
+     * @param {{ orientation: 'left' | 'right' | 'top' | 'bottom', ownerIndex?: string, name?: string }} pin
+     * @param {number} baseX
+     * @param {Map<string, number>} explicitOwnerPinLabelOffsets
+     * @returns {number}
+     */
+    static resolveExplicitOwnerPinNumberX(
+        pin,
+        baseX,
+        explicitOwnerPinLabelOffsets
+    ) {
+        const key = SchematicOwnerPinLabelLayout.buildOwnerPinLabelKey(
+            pin.ownerIndex,
+            pin.name
+        )
+        const delta = Number(explicitOwnerPinLabelOffsets.get(key) || 0)
+
+        if (!delta) {
+            return baseX
+        }
+
+        switch (pin.orientation) {
+            case 'left':
+                return baseX - delta
+            case 'right':
+                return baseX + delta
+            default:
+                return baseX
+        }
+    }
+}