altium-toolkit 1.1.2 → 1.1.22

package/src/ui/SchematicColorResolver.mjs

@@ -31,6 +31,7 @@ export class SchematicColorResolver {
      * Resolves one SVG color value to a schematic theme variable.
      * @param {string | undefined} color
      * @param {string} fallbackVariable
+     * @param {boolean} [preserveUnknown]
      * @returns {string}
      */
     static resolveColor(color, fallbackVariable, preserveUnknown = false) {
@@ -59,10 +60,36 @@ export class SchematicColorResolver {
             : SchematicColorResolver.#toVariable(fallbackVariable)
     }
 
+    /**
+     * Resolves one non-text primitive color, using the semantic fallback when
+     * source artwork only supplies the default black text color.
+     * @param {string | undefined} color
+     * @param {string} fallbackVariable
+     * @param {boolean} [preserveUnknown]
+     * @returns {string}
+     */
+    static resolveNonTextColor(
+        color,
+        fallbackVariable,
+        preserveUnknown = false
+    ) {
+        const resolved = SchematicColorResolver.resolveColor(
+            color,
+            fallbackVariable,
+            preserveUnknown
+        )
+
+        return resolved ===
+            SchematicColorResolver.#toVariable('--schematic-text-color')
+            ? SchematicColorResolver.#toVariable(fallbackVariable)
+            : resolved
+    }
+
     /**
      * Resolves one SVG fill value to a schematic theme variable.
      * @param {string | undefined} fill
      * @param {string} fallbackVariable
+     * @param {boolean} [preserveUnknown]
      * @returns {string}
      */
     static resolveFill(fill, fallbackVariable, preserveUnknown = false) {
@@ -100,6 +127,121 @@ export class SchematicColorResolver {
             : SchematicColorResolver.#toVariable(fallbackVariable)
     }
 
+    /**
+     * Resolves an explicitly authored source stroke color without mapping it to
+     * a semantic theme token.
+     * @param {string | undefined} color
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static resolveSourceColor(color, fallbackVariable) {
+        return SchematicColorResolver.#resolveSourcePaint(
+            color,
+            fallbackVariable
+        )
+    }
+
+    /**
+     * Resolves an explicitly authored source fill color without mapping it to a
+     * semantic theme token.
+     * @param {string | undefined} fill
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static resolveSourceFill(fill, fallbackVariable) {
+        return SchematicColorResolver.#resolveSourcePaint(
+            fill,
+            fallbackVariable
+        )
+    }
+
+    /**
+     * Resolves an authored source stroke through a muted source palette.
+     * @param {string | undefined} color
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static resolveMutedSourceColor(color, fallbackVariable) {
+        return SchematicColorResolver.#resolveMutedSourcePaint(
+            color,
+            fallbackVariable
+        )
+    }
+
+    /**
+     * Resolves an authored source fill through a muted source palette.
+     * @param {string | undefined} fill
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static resolveMutedSourceFill(fill, fallbackVariable) {
+        return SchematicColorResolver.#resolveMutedSourcePaint(
+            fill,
+            fallbackVariable
+        )
+    }
+
+    /**
+     * Resolves one literal source paint value while preserving SVG control
+     * values and falling back only when no source paint exists.
+     * @param {string | undefined} paint
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static #resolveSourcePaint(paint, fallbackVariable) {
+        const normalized = SchematicColorResolver.#normalizeColor(paint)
+
+        if (!normalized) {
+            return SchematicColorResolver.#toVariable(fallbackVariable)
+        }
+
+        if (
+            normalized === 'none' ||
+            normalized === 'transparent' ||
+            normalized.startsWith('var(')
+        ) {
+            return normalized
+        }
+
+        return normalized
+    }
+
+    /**
+     * Resolves one literal source paint while reducing vivid palette colors.
+     * @param {string | undefined} paint
+     * @param {string} fallbackVariable
+     * @returns {string}
+     */
+    static #resolveMutedSourcePaint(paint, fallbackVariable) {
+        const normalized = SchematicColorResolver.#normalizeColor(paint)
+
+        if (!normalized) {
+            return SchematicColorResolver.#toVariable(fallbackVariable)
+        }
+
+        if (
+            normalized === 'none' ||
+            normalized === 'transparent' ||
+            normalized.startsWith('var(')
+        ) {
+            return normalized
+        }
+
+        const rgb = SchematicColorResolver.#parseHexColor(normalized)
+        if (!rgb) {
+            return normalized
+        }
+
+        const hsl = SchematicColorResolver.#rgbToHsl(rgb)
+        const mutedRgb = SchematicColorResolver.#hslToRgb({
+            h: hsl.h,
+            s: Math.min(hsl.s, 45),
+            l: Math.min(Math.max(hsl.l, 30), 68)
+        })
+
+        return SchematicColorResolver.#formatHexColor(mutedRgb)
+    }
+
     /**
      * Normalizes one raw color string for token lookup.
      * @param {string | undefined} color
@@ -111,6 +253,127 @@ export class SchematicColorResolver {
             .toLowerCase()
     }
 
+    /**
+     * Parses a six-digit hex color.
+     * @param {string} color
+     * @returns {{ r: number, g: number, b: number } | null}
+     */
+    static #parseHexColor(color) {
+        const match = /^#([0-9a-f]{6})$/u.exec(color)
+        if (!match) {
+            return null
+        }
+
+        const value = match[1]
+        return {
+            r: Number.parseInt(value.slice(0, 2), 16),
+            g: Number.parseInt(value.slice(2, 4), 16),
+            b: Number.parseInt(value.slice(4, 6), 16)
+        }
+    }
+
+    /**
+     * Converts RGB channels to HSL.
+     * @param {{ r: number, g: number, b: number }} color
+     * @returns {{ h: number, s: number, l: number }}
+     */
+    static #rgbToHsl(color) {
+        const r = color.r / 255
+        const g = color.g / 255
+        const b = color.b / 255
+        const max = Math.max(r, g, b)
+        const min = Math.min(r, g, b)
+        let h = 0
+        let s = 0
+        const l = ((max + min) / 2) * 100
+
+        if (max !== min) {
+            const delta = max - min
+            s =
+                ((max + min) / 2 > 0.5
+                    ? delta / (2 - max - min)
+                    : delta / (max + min)) * 100
+
+            switch (max) {
+                case r:
+                    h = (g - b) / delta + (g < b ? 6 : 0)
+                    break
+                case g:
+                    h = (b - r) / delta + 2
+                    break
+                default:
+                    h = (r - g) / delta + 4
+                    break
+            }
+
+            h /= 6
+        }
+
+        return { h, s, l }
+    }
+
+    /**
+     * Converts HSL channels to RGB.
+     * @param {{ h: number, s: number, l: number }} color
+     * @returns {{ r: number, g: number, b: number }}
+     */
+    static #hslToRgb(color) {
+        const s = color.s / 100
+        const l = color.l / 100
+
+        if (s === 0) {
+            const value = Math.round(l * 255)
+            return { r: value, g: value, b: value }
+        }
+
+        const q = l < 0.5 ? l * (1 + s) : l + s - l * s
+        const p = 2 * l - q
+        const r = SchematicColorResolver.#hueToRgb(p, q, color.h + 1 / 3)
+        const g = SchematicColorResolver.#hueToRgb(p, q, color.h)
+        const b = SchematicColorResolver.#hueToRgb(p, q, color.h - 1 / 3)
+
+        return {
+            r: Math.round(r * 255),
+            g: Math.round(g * 255),
+            b: Math.round(b * 255)
+        }
+    }
+
+    /**
+     * Converts one hue channel to RGB.
+     * @param {number} p
+     * @param {number} q
+     * @param {number} t
+     * @returns {number}
+     */
+    static #hueToRgb(p, q, t) {
+        let value = t
+        if (value < 0) value += 1
+        if (value > 1) value -= 1
+        if (value < 1 / 6) return p + (q - p) * 6 * value
+        if (value < 1 / 2) return q
+        if (value < 2 / 3) return p + (q - p) * (2 / 3 - value) * 6
+        return p
+    }
+
+    /**
+     * Formats RGB channels as a hex color.
+     * @param {{ r: number, g: number, b: number }} color
+     * @returns {string}
+     */
+    static #formatHexColor(color) {
+        return (
+            '#' +
+            [color.r, color.g, color.b]
+                .map((channel) =>
+                    Math.max(0, Math.min(255, channel))
+                        .toString(16)
+                        .padStart(2, '0')
+                )
+                .join('')
+        )
+    }
+
     /**
      * Wraps one CSS custom property name in `var(...)` markup.
      * @param {string} variableName

package/src/ui/SchematicContentLayout.mjs

@@ -721,7 +721,12 @@ export class SchematicContentLayout {
         }
 
         for (const text of schematic?.texts || []) {
-            coordinates.push([text.x, projectSchematicY(sheetHeight, text.y)])
+            coordinates.push(
+                ...SchematicContentLayout.#collectRenderedTextPoints(
+                    text,
+                    sheetHeight
+                )
+            )
         }
 
         for (const component of schematic?.components || []) {
@@ -829,6 +834,58 @@ export class SchematicContentLayout {
         }))
     }
 
+    /**
+     * Collects rendered bounds points for a text primitive.
+     * @param {{ x?: number, y?: number, recordType?: string, cornerX?: number, cornerY?: number, noteLines?: string[] }} text Text primitive.
+     * @param {number} sheetHeight Sheet height.
+     * @returns {number[][]}
+     */
+    static #collectRenderedTextPoints(text, sheetHeight) {
+        const x = Number(text?.x)
+        const y = Number(text?.y)
+
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+            return []
+        }
+
+        if (SchematicContentLayout.#hasRenderedTextFrame(text)) {
+            const cornerX = Number(text.cornerX)
+            const cornerY = Number(text.cornerY)
+            const left = Math.min(x, cornerX)
+            const right = Math.max(x, cornerX)
+            const top = Math.min(
+                projectSchematicY(sheetHeight, y),
+                projectSchematicY(sheetHeight, cornerY)
+            )
+            const bottom = Math.max(
+                projectSchematicY(sheetHeight, y),
+                projectSchematicY(sheetHeight, cornerY)
+            )
+
+            return [
+                [left, top],
+                [right, bottom]
+            ]
+        }
+
+        return [[x, projectSchematicY(sheetHeight, y)]]
+    }
+
+    /**
+     * Returns true when a text primitive renders as a framed note/callout box.
+     * @param {{ recordType?: string, cornerX?: number, cornerY?: number, noteLines?: string[] }} text Text primitive.
+     * @returns {boolean}
+     */
+    static #hasRenderedTextFrame(text) {
+        const recordType = String(text?.recordType || '')
+
+        return Boolean(
+            (recordType === '28' || recordType === '209') &&
+            Number.isFinite(Number(text?.cornerX)) &&
+            Number.isFinite(Number(text?.cornerY))
+        )
+    }
+
     /**
      * Computes the inner endpoint for one schematic pin stub.
      * @param {{ x: number, y: number, length: number, orientation: 'left' | 'right' | 'top' | 'bottom' }} pin

package/src/ui/SchematicDirectiveRenderer.mjs

@@ -50,32 +50,45 @@ export class SchematicDirectiveRenderer {
                 return SchematicDirectiveRenderer.#buildRouteMarkup(
                     directive,
                     sheetHeight,
-                    sheet
+                    sheet,
+                    'route'
                 )
             default:
-                return ''
+                return directive?.name
+                    ? SchematicDirectiveRenderer.#buildRouteMarkup(
+                          directive,
+                          sheetHeight,
+                          sheet,
+                          'parameter-set'
+                      )
+                    : ''
         }
     }
 
     /**
-     * Builds the labeled route-callout marker for one differential-pair
-     * routing directive.
-     * @param {{ x: number, y: number, color: string, orientation?: number }} directive
+     * Builds the labeled info-callout marker for one parameter-set directive.
+     * @param {{ x: number, y: number, color: string, name: string, orientation?: number }} directive
      * @param {number} sheetHeight
      * @param {{ fonts?: Record<string, { size: number, family: string, bold: boolean }> }} sheet
+     * @param {string} classModifier
      * @returns {string}
      */
-    static #buildRouteMarkup(directive, sheetHeight, sheet) {
+    static #buildRouteMarkup(directive, sheetHeight, sheet, classModifier) {
         const color = SchematicColorResolver.resolveColor(
             directive.color,
             '--schematic-alert-color'
         )
         const projectedY = projectSchematicY(sheetHeight, directive.y)
-        const verticalDirection =
-            Number(directive.orientation || 0) === 3 ? 1 : -1
+        const direction = SchematicDirectiveRenderer.#resolveCalloutDirection(
+            directive.orientation
+        )
         const circleRadius = 7
-        const circleCenterY = projectedY + verticalDirection * 18
-        const leaderEndY = circleCenterY - verticalDirection * circleRadius
+        const calloutDistance =
+            SchematicDirectiveRenderer.#resolveCalloutDistance(direction)
+        const circleCenterX = directive.x + direction.x * calloutDistance
+        const circleCenterY = projectedY + direction.y * calloutDistance
+        const leaderEndX = circleCenterX - direction.x * circleRadius
+        const leaderEndY = circleCenterY - direction.y * circleRadius
         const labelOptions =
             SchematicTypography.buildViewerSchematicFontOptions(sheet)
         const infoOptions = {
@@ -83,26 +96,32 @@ export class SchematicDirectiveRenderer {
             fontSize: Math.max(Number(labelOptions.fontSize || 9) - 1, 6),
             fontWeight: 700
         }
-        const labelY =
-            circleCenterY +
-            verticalDirection *
-                (circleRadius + Number(labelOptions.fontSize || 9))
+        const labelPlacement =
+            SchematicDirectiveRenderer.#resolveLabelPlacement(
+                circleCenterX,
+                circleCenterY,
+                direction,
+                circleRadius,
+                Number(labelOptions.fontSize || 9)
+            )
 
         return (
-            '<g class="schematic-directive schematic-directive--route">' +
+            '<g class="schematic-directive schematic-directive--' +
+            escapeHtml(classModifier) +
+            '">' +
             '<line x1="' +
             formatNumber(directive.x) +
             '" y1="' +
             formatNumber(projectedY) +
             '" x2="' +
-            formatNumber(directive.x) +
+            formatNumber(leaderEndX) +
             '" y2="' +
             formatNumber(leaderEndY) +
             '" stroke="' +
             escapeHtml(color) +
             '" stroke-width="1" />' +
             '<circle cx="' +
-            formatNumber(directive.x) +
+            formatNumber(circleCenterX) +
             '" cy="' +
             formatNumber(circleCenterY) +
             '" r="' +
@@ -112,17 +131,20 @@ export class SchematicDirectiveRenderer {
             '" stroke-width="1" />' +
             createSvgText(
                 'schematic-directive-label',
-                directive.x,
-                labelY,
+                labelPlacement.x,
+                labelPlacement.y,
                 String(directive.name || ''),
                 color,
-                'middle',
+                labelPlacement.anchor,
                 labelOptions
             ) +
             createSvgText(
                 'schematic-directive-info',
-                directive.x,
-                circleCenterY + Number(infoOptions.fontSize || 8) * 0.34,
+                circleCenterX,
+                circleCenterY +
+                    SchematicDirectiveRenderer.#baselineOffset(
+                        Number(infoOptions.fontSize || 8)
+                    ),
                 'i',
                 color,
                 'middle',
@@ -132,6 +154,95 @@ export class SchematicDirectiveRenderer {
         )
     }
 
+    /**
+     * Resolves Altium's four-way callout orientation into an outward vector.
+     * @param {number | undefined} orientation
+     * @returns {{ x: number, y: number }}
+     */
+    static #resolveCalloutDirection(orientation) {
+        switch (Number(orientation || 0)) {
+            case 1:
+                return { x: 0, y: -1 }
+            case 2:
+                return { x: -1, y: 0 }
+            case 3:
+                return { x: 0, y: 1 }
+            default:
+                return { x: 1, y: 0 }
+        }
+    }
+
+    /**
+     * Resolves the distance from a directive anchor to its info marker center.
+     * @param {{ x: number, y: number }} direction
+     * @returns {number}
+     */
+    static #resolveCalloutDistance(direction) {
+        return direction.y < 0 ? 12 : 18
+    }
+
+    /**
+     * Resolves label placement outside one directive info marker.
+     * @param {number} circleCenterX
+     * @param {number} circleCenterY
+     * @param {{ x: number, y: number }} direction
+     * @param {number} circleRadius
+     * @param {number} fontSize
+     * @returns {{ x: number, y: number, anchor: 'start' | 'middle' | 'end' }}
+     */
+    static #resolveLabelPlacement(
+        circleCenterX,
+        circleCenterY,
+        direction,
+        circleRadius,
+        fontSize
+    ) {
+        const labelDistance = circleRadius + fontSize
+
+        if (direction.x < 0) {
+            return {
+                x: circleCenterX - labelDistance,
+                y:
+                    circleCenterY +
+                    SchematicDirectiveRenderer.#baselineOffset(fontSize),
+                anchor: 'end'
+            }
+        }
+
+        if (direction.x > 0) {
+            return {
+                x: circleCenterX + labelDistance,
+                y:
+                    circleCenterY +
+                    SchematicDirectiveRenderer.#baselineOffset(fontSize),
+                anchor: 'start'
+            }
+        }
+
+        if (direction.y < 0) {
+            return {
+                x: circleCenterX,
+                y: circleCenterY - circleRadius - 2,
+                anchor: 'middle'
+            }
+        }
+
+        return {
+            x: circleCenterX,
+            y: circleCenterY + direction.y * labelDistance,
+            anchor: 'middle'
+        }
+    }
+
+    /**
+     * Returns a baseline offset that visually centers text around a marker.
+     * @param {number} fontSize
+     * @returns {number}
+     */
+    static #baselineOffset(fontSize) {
+        return fontSize * 0.34
+    }
+
     /**
      * Builds the paired-trace differential-pair marker glyph.
      * @param {{ x: number, y: number, color: string }} directive