smithkit 0.1.1 → 0.3.0

package/dist/lib/svg/ImageExporter.js

@@ -0,0 +1,211 @@
+/** Compose SVG snapshots and rasterize PNG reports without changing live chart nodes. */
+export class ImageExporter {
+    constructor() { }
+    static layout(sources, options, legend) {
+        const { width: requestedWidth, height: requestedHeight, background } = options;
+        for (const value of [requestedWidth, requestedHeight]) {
+            if (value !== undefined && (!Number.isInteger(value) || value < 1 || value > 8192)) {
+                throw new RangeError('Export dimensions must be integers from 1 to 8192 pixels.');
+            }
+        }
+        if (background !== undefined &&
+            (!CSS.supports('color', background) ||
+                /\b(var|currentcolor|inherit|initial|unset|revert|light-dark)\b/i.test(background))) {
+            throw new RangeError('Export background must be a concrete CSS color or transparent.');
+        }
+        const snapshots = sources.map((source) => {
+            const svg = new DOMParser().parseFromString(source, 'image/svg+xml').documentElement;
+            if (background !== undefined) {
+                svg.querySelectorAll('[data-export-background]').forEach((node) => node.remove());
+            }
+            return {
+                svg,
+                width: Number(svg.getAttribute('width')),
+                height: Number(svg.getAttribute('height')),
+            };
+        });
+        const gap = snapshots.length > 1 ? 24 : 0;
+        const contentWidth = Math.max(...snapshots.map((source) => source.width));
+        const contentHeight = snapshots.reduce((sum, source) => sum + source.height, 0) + gap * (snapshots.length - 1);
+        const canvas = document.createElement('canvas');
+        const context = canvas.getContext('2d');
+        if (!context) {
+            throw new Error('Image export requires a Canvas 2D context.');
+        }
+        context.font = `14px ${legend?.fontFamily ?? 'sans-serif'}`;
+        const rows = (legend?.entries ?? []).flatMap((entry) => {
+            const lines = ImageExporter.wrap(entry.name, Math.max(1, contentWidth - 64), context);
+            return lines.map((text, index) => ({ text, color: entry.color, swatch: index === 0 }));
+        });
+        const legendHeight = rows.length ? 32 + rows.length * 22 : 0;
+        const naturalHeight = contentHeight + legendHeight;
+        const width = requestedWidth ??
+            Math.max(1, Math.round(requestedHeight === undefined
+                ? contentWidth
+                : (requestedHeight * contentWidth) / naturalHeight));
+        const height = requestedHeight ?? Math.max(1, Math.round((width * naturalHeight) / contentWidth));
+        if (width > 8192 || height > 8192 || width * height > 33_554_432) {
+            throw new RangeError('Image output must not exceed 8192 pixels per side or 32 megapixels.');
+        }
+        const scale = Math.min(width / contentWidth, height / naturalHeight);
+        return {
+            snapshots,
+            gap,
+            contentWidth,
+            contentHeight,
+            context,
+            canvas,
+            rows,
+            legendHeight,
+            width,
+            height,
+            scale,
+            naturalHeight,
+        };
+    }
+    static async png(sources, options, legend) {
+        const snapshotOptions = { ...options };
+        await document.fonts.ready;
+        const { snapshots, gap, contentWidth, contentHeight, context, canvas, rows, legendHeight, width, height, scale, naturalHeight, } = ImageExporter.layout(sources, snapshotOptions, legend);
+        const background = snapshotOptions.background;
+        canvas.width = width;
+        canvas.height = height;
+        // Explicit backgrounds replace component backgrounds; omission preserves them.
+        if (background !== undefined) {
+            context.fillStyle = background;
+            context.fillRect(0, 0, width, height);
+        }
+        context.translate((width - contentWidth * scale) / 2, (height - naturalHeight * scale) / 2);
+        context.scale(scale, scale);
+        let y = 0;
+        for (const source of snapshots) {
+            const url = URL.createObjectURL(new Blob([new XMLSerializer().serializeToString(source.svg)], {
+                type: 'image/svg+xml;charset=utf-8',
+            }));
+            try {
+                const image = new Image();
+                image.src = url;
+                await image.decode();
+                context.drawImage(image, (contentWidth - source.width) / 2, y, source.width, source.height);
+            }
+            finally {
+                URL.revokeObjectURL(url);
+            }
+            y += source.height + gap;
+        }
+        if (legend && rows.length) {
+            // Use the chart's own background for the footer unless explicitly overridden.
+            const chartBackground = snapshots[0].svg
+                .querySelector('[data-export-background]')
+                ?.getAttribute('fill');
+            if (background === undefined && chartBackground) {
+                context.fillStyle = chartBackground;
+                context.fillRect(0, contentHeight, contentWidth, legendHeight);
+            }
+            context.font = `14px ${legend.fontFamily}`;
+            context.textBaseline = 'middle';
+            for (const [index, row] of rows.entries()) {
+                const y = contentHeight + 24 + index * 22;
+                if (row.swatch) {
+                    context.strokeStyle = row.color;
+                    context.lineWidth = 3;
+                    context.beginPath();
+                    context.moveTo(16, y);
+                    context.lineTo(40, y);
+                    context.stroke();
+                }
+                context.fillStyle = legend.textColor;
+                context.fillText(row.text, 48, y);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            canvas.toBlob((blob) => {
+                if (blob) {
+                    resolve(blob);
+                }
+                else {
+                    reject(new Error('The browser could not encode the PNG image.'));
+                }
+            }, 'image/png');
+        });
+    }
+    static svg(sources, options, legend) {
+        const { snapshots, gap, contentWidth, contentHeight, rows, legendHeight, width, height, scale, naturalHeight, } = ImageExporter.layout(sources, options, legend);
+        const namespace = 'http://www.w3.org/2000/svg';
+        const root = document.createElementNS(namespace, 'svg');
+        const left = -(width / scale - contentWidth) / 2;
+        const top = -(height / scale - naturalHeight) / 2;
+        root.setAttribute('width', String(width));
+        root.setAttribute('height', String(height));
+        root.setAttribute('viewBox', `${left} ${top} ${width / scale} ${height / scale}`);
+        const append = (tag, attributes) => {
+            const node = document.createElementNS(namespace, tag);
+            for (const [name, value] of Object.entries(attributes)) {
+                node.setAttribute(name, String(value));
+            }
+            root.appendChild(node);
+            return node;
+        };
+        if (options.background !== undefined) {
+            append('rect', {
+                x: left,
+                y: top,
+                width: width / scale,
+                height: height / scale,
+                fill: options.background,
+            });
+        }
+        let y = 0;
+        for (const source of snapshots) {
+            source.svg.setAttribute('x', String((contentWidth - source.width) / 2));
+            source.svg.setAttribute('y', String(y));
+            root.appendChild(source.svg);
+            y += source.height + gap;
+        }
+        if (legend && rows.length) {
+            const chartBackground = snapshots[0].svg
+                .querySelector('[data-export-background]')
+                ?.getAttribute('fill');
+            if (options.background === undefined && chartBackground) {
+                append('rect', {
+                    x: 0,
+                    y: contentHeight,
+                    width: contentWidth,
+                    height: legendHeight,
+                    fill: chartBackground,
+                });
+            }
+            for (const [index, row] of rows.entries()) {
+                const y = contentHeight + 24 + index * 22;
+                if (row.swatch) {
+                    append('line', { x1: 16, x2: 40, y1: y, y2: y, stroke: row.color, 'stroke-width': 3 });
+                }
+                const text = append('text', {
+                    x: 48,
+                    y,
+                    fill: legend.textColor,
+                    'font-size': 14,
+                    'font-family': legend.fontFamily,
+                    'dominant-baseline': 'central',
+                });
+                text.textContent = row.text;
+            }
+        }
+        return new XMLSerializer().serializeToString(root);
+    }
+    static wrap(text, width, context) {
+        const lines = [];
+        let line = '';
+        for (const character of text) {
+            if (character === '\n' || (line && context.measureText(line + character).width > width)) {
+                lines.push(line);
+                line = '';
+            }
+            if (character !== '\n') {
+                line += character;
+            }
+        }
+        lines.push(line);
+        return lines;
+    }
+}

package/dist/lib/svg/LabelLayout.d.ts

@@ -0,0 +1,17 @@
+/** Responsive label placement measured in the default view, independent of user zoom. */
+export declare class LabelLayout {
+    private readonly viewport;
+    private readonly container;
+    private readonly baseView;
+    private width;
+    private height;
+    private readonly resizedFonts;
+    constructor(viewport: SVGSVGElement, container: SVGGElement, baseView: {
+        x: number;
+        y: number;
+        k: number;
+    });
+    update(force?: boolean): void;
+    private static transformBox;
+    private static overlaps;
+}

package/dist/lib/svg/LabelLayout.js

@@ -0,0 +1,145 @@
+/** Responsive label placement measured in the default view, independent of user zoom. */
+export class LabelLayout {
+    viewport;
+    container;
+    baseView;
+    width = 0;
+    height = 0;
+    resizedFonts = new Map();
+    constructor(viewport, container, baseView) {
+        this.viewport = viewport;
+        this.container = container;
+        this.baseView = baseView;
+    }
+    update(force = false) {
+        const viewport = this.viewport.getBoundingClientRect();
+        if (!this.viewport.isConnected || viewport.width <= 0 || viewport.height <= 0) {
+            return;
+        }
+        if (!force && viewport.width === this.width && viewport.height === this.height) {
+            return;
+        }
+        this.width = viewport.width;
+        this.height = viewport.height;
+        const rootMatrix = this.viewport.getScreenCTM();
+        const containerMatrix = this.container.getScreenCTM();
+        if (!rootMatrix || !containerMatrix) {
+            return;
+        }
+        const reference = rootMatrix.translate(this.baseView.x, this.baseView.y).scale(this.baseView.k);
+        const normalize = reference.multiply(containerMatrix.inverse());
+        // Peripheral rulers retain their complete, fixed-scale lettering. Only grid
+        // labels participate in thinning and minimum-font-size adjustments.
+        const labels = [...this.container.querySelectorAll('text')].filter((label) => !label.closest('[data-label-layer=peripheral-scales]'));
+        const view = this.viewport.ownerDocument.defaultView;
+        // Restore only properties owned by this layout before measuring the base styling.
+        for (const label of labels) {
+            if (label.hasAttribute('data-label-hidden')) {
+                label.removeAttribute('visibility');
+                label.removeAttribute('data-label-hidden');
+            }
+            const previousFont = this.resizedFonts.get(label);
+            if (previousFont !== undefined) {
+                if (previousFont) {
+                    label.style.fontSize = previousFont;
+                }
+                else {
+                    label.style.removeProperty('font-size');
+                }
+            }
+        }
+        this.resizedFonts.clear();
+        const styles = new Map();
+        const style = (element) => {
+            let result = styles.get(element);
+            if (!result) {
+                result = view.getComputedStyle(element);
+                styles.set(element, result);
+            }
+            return result;
+        };
+        const candidates = labels.flatMap((label, order) => {
+            for (let parent = label; parent; parent = parent.parentElement) {
+                const computed = style(parent);
+                if (computed.display === 'none' ||
+                    computed.visibility === 'hidden' ||
+                    Number(computed.opacity) === 0) {
+                    return [];
+                }
+                if (parent === this.viewport) {
+                    break;
+                }
+            }
+            const screenMatrix = label.getScreenCTM();
+            const matrix = screenMatrix ? normalize.multiply(screenMatrix) : null;
+            const scale = matrix ? Math.hypot(matrix.a, matrix.b) : 0;
+            if (scale <= 0) {
+                return [];
+            }
+            return [
+                {
+                    label,
+                    order,
+                    scale,
+                    matrix: matrix,
+                    baseSize: parseFloat(style(label).fontSize),
+                    priority: Number(label.dataset.labelPriority ?? 0),
+                },
+            ];
+        });
+        // Batch font changes before reading bounds to avoid alternating layout reads/writes.
+        for (const { label, scale, baseSize } of candidates) {
+            if (Number.isFinite(baseSize) && baseSize * scale < 9) {
+                this.resizedFonts.set(label, label.style.fontSize);
+                label.style.fontSize = `${9 / scale}px`;
+            }
+        }
+        const measured = candidates.map((entry) => ({
+            ...entry,
+            box: LabelLayout.transformBox(entry.label.getBBox(), entry.matrix),
+        }));
+        measured.sort((a, b) => b.priority - a.priority || a.order - b.order);
+        const occupied = [];
+        const hidden = [];
+        for (const { label, box } of measured) {
+            const outside = box.right <= box.left ||
+                box.bottom <= box.top ||
+                box.left < viewport.left + 1 ||
+                box.right > viewport.right - 1 ||
+                box.top < viewport.top + 1 ||
+                box.bottom > viewport.bottom - 1;
+            const collision = occupied.some((other) => LabelLayout.overlaps(box, other));
+            if (outside || collision) {
+                hidden.push(label);
+            }
+            else {
+                occupied.push(box);
+            }
+        }
+        for (const label of hidden) {
+            label.setAttribute('visibility', 'hidden');
+            label.setAttribute('data-label-hidden', 'true');
+        }
+    }
+    static transformBox(box, matrix) {
+        const points = [
+            new DOMPoint(box.x, box.y),
+            new DOMPoint(box.x + box.width, box.y),
+            new DOMPoint(box.x, box.y + box.height),
+            new DOMPoint(box.x + box.width, box.y + box.height),
+        ].map((point) => point.matrixTransform(matrix));
+        return {
+            left: Math.min(...points.map((point) => point.x)),
+            right: Math.max(...points.map((point) => point.x)),
+            top: Math.min(...points.map((point) => point.y)),
+            bottom: Math.max(...points.map((point) => point.y)),
+        };
+    }
+    static overlaps(a, b) {
+        const gap = 2;
+        return (a.left < b.right + gap &&
+            a.right + gap > b.left &&
+            a.top < b.bottom + gap &&
+            a.bottom + gap > b.top);
+    }
+}

package/dist/lib/svg/MarkerLegend.d.ts

@@ -0,0 +1,12 @@
+import type { MarkerSnapshot, TraceInfo } from '../measurements.js';
+import type { MarkerLegendOptions } from './export.js';
+/** Format detached marker readings for the shared SVG/PNG report footer. */
+export declare class MarkerLegend {
+    private constructor();
+    static entries(traces: readonly TraceInfo[], reading: (id: string) => MarkerSnapshot, options: true | MarkerLegendOptions): {
+        name: string;
+        color: string;
+    }[];
+    private static field;
+    private static number;
+}

package/dist/lib/svg/MarkerLegend.js

@@ -0,0 +1,63 @@
+import { SmithFormatter } from '../SmithFormatter.js';
+/** Format detached marker readings for the shared SVG/PNG report footer. */
+export class MarkerLegend {
+    constructor() { }
+    static entries(traces, reading, options) {
+        const { markerIds, fields = ['frequency', 'impedance'] } = options === true ? {} : options;
+        const knownIds = new Set(traces.flatMap((trace) => trace.markers.map((marker) => marker.id)));
+        if (markerIds?.some((id) => !knownIds.has(id))) {
+            throw new RangeError('Marker legend contains an unknown marker ID.');
+        }
+        const available = [
+            'frequency',
+            'impedance',
+            'admittance',
+            'reflectionCoefficient',
+            'vswr',
+            'returnLoss',
+        ];
+        if (fields.some((field) => !available.includes(field))) {
+            throw new RangeError('Marker legend contains an unknown field.');
+        }
+        const selected = markerIds === undefined ? undefined : new Set(markerIds);
+        return traces
+            .filter((trace) => trace.visible)
+            .flatMap((trace) => trace.markers
+            .filter((marker) => selected === undefined || selected.has(marker.id))
+            .map((marker) => {
+            const snapshot = reading(marker.id);
+            return {
+                color: trace.color,
+                name: [
+                    `${trace.name} · Marker ${marker.number}`,
+                    ...[...new Set(fields)].map((field) => MarkerLegend.field(snapshot, field)),
+                ].join(' · '),
+            };
+        }));
+    }
+    static field(marker, field) {
+        switch (field) {
+            case 'frequency':
+                return `f = ${SmithFormatter.number(marker.frequencyHz)}Hz`;
+            case 'impedance':
+                return `Z = ${marker.impedanceOhms?.toString(3) ?? '∞'} Ω`;
+            case 'admittance':
+                return `Y = ${marker.admittanceSiemens?.mul(1000).toString(3) ?? '∞'} mS`;
+            case 'reflectionCoefficient':
+                return `Γ = ${marker.reflectionCoefficient.toString(3)}`;
+            case 'vswr':
+                return `VSWR = ${MarkerLegend.number(marker.vswr)}${marker.vswr === undefined ? '' : ' : 1'}`;
+            case 'returnLoss':
+                return `Return loss = ${MarkerLegend.number(marker.returnLossDb)} dB`;
+        }
+    }
+    static number(value) {
+        if (value === undefined || Number.isNaN(value)) {
+            return '—';
+        }
+        if (!Number.isFinite(value)) {
+            return value < 0 ? '−∞' : '∞';
+        }
+        return String(Number(value.toPrecision(4)));
+    }
+}

package/dist/lib/{draw → svg}/SmithArc.d.ts

@@ -1,4 +1,4 @@
-import { Point } from '../shapes/Point.js';
+import { Point } from '../math/geometry.js';
 import { SmithShape } from './SmithShape.js';
 import { SmithDrawOptions } from './SmithDrawOptions.js';
 export declare class SmithArc extends SmithShape {

package/dist/lib/{draw → svg}/SmithCircle.d.ts

@@ -1,4 +1,4 @@
-import { Circle } from '../shapes/Circle.js';
+import { Circle } from '../math/geometry.js';
 import { SmithShape } from './SmithShape.js';
 import { SmithDrawOptions } from './SmithDrawOptions.js';
 export declare class SmithCircle extends SmithShape {

package/dist/lib/{draw → svg}/SmithLine.d.ts

@@ -1,4 +1,4 @@
-import { Point } from '../shapes/Point.js';
+import { Point } from '../math/geometry.js';
 import { SmithShape } from './SmithShape.js';
 import { SmithDrawOptions } from './SmithDrawOptions.js';
 export declare class SmithLine extends SmithShape {

package/dist/lib/{draw → svg}/SmithScaler.d.ts

@@ -1,8 +1,5 @@
 import * as d3 from 'd3';
-import { Circle } from '../shapes/Circle.js';
-import { Point } from '../shapes/Point.js';
-import { Line } from '../shapes/Line.js';
-import { Arc } from '../shapes/Arc.js';
+import type { Circle, Point, Line, Arc } from '../math/geometry.js';
 export declare class SmithScaler {
     readonly x: d3.ScaleLinear<number, number>;
     readonly y: d3.ScaleLinear<number, number>;

package/dist/lib/{draw → svg}/SmithText.d.ts

@@ -1,4 +1,4 @@
-import { Point } from '../shapes/Point.js';
+import { Point } from '../math/geometry.js';
 import { SmithShape } from './SmithShape.js';
 interface TextOptions {
     dx?: string;

package/dist/lib/svg/SvgExporter.d.ts

@@ -0,0 +1,19 @@
+/** Captures rendered SVG with presentation styles resolved in its source document. */
+export declare class SvgExporter {
+    private constructor();
+    private static readonly namespace;
+    private static readonly properties;
+    private static readonly nonInherited;
+    static chart(source: SVGElement): string;
+    /** Preserve the current CSS layout of separate scale SVGs in one SVG document. */
+    static scales(container: HTMLElement, axes: readonly SVGSVGElement[], customize?: (copy: SVGElement, index: number) => void, caption?: {
+        text: string;
+        color: string;
+        fontFamily: string;
+    }): string;
+    private static background;
+    private static bounds;
+    private static copy;
+    private static size;
+    private static serialize;
+}