smithkit 0.2.0 → 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/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/svg/SvgExporter.d.ts

@@ -6,7 +6,12 @@ export declare class SvgExporter {
     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[]): string;
+    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;

package/dist/lib/svg/SvgExporter.js

@@ -49,25 +49,70 @@ export class SvgExporter {
     static chart(source) {
         const bounds = SvgExporter.bounds(source);
         const copy = SvgExporter.copy(source);
+        SvgExporter.background(copy, source);
         SvgExporter.size(copy, bounds.width, bounds.height);
         return SvgExporter.serialize(copy);
     }
     /** Preserve the current CSS layout of separate scale SVGs in one SVG document. */
-    static scales(container, axes) {
+    static scales(container, axes, customize, caption) {
         const bounds = SvgExporter.bounds(container);
         const root = container.ownerDocument.createElementNS(SvgExporter.namespace, 'svg');
-        root.setAttribute('viewBox', `0 0 ${bounds.width} ${bounds.height}`);
-        SvgExporter.size(root, bounds.width, bounds.height);
-        for (const axis of axes) {
+        const lines = [];
+        if (caption?.text) {
+            const context = document.createElement('canvas').getContext('2d');
+            context.font = `14px ${caption.fontFamily}`;
+            let line = '';
+            for (const character of caption.text) {
+                if (character === '\n' ||
+                    (line && context.measureText(line + character).width > Math.max(1, bounds.width - 32))) {
+                    lines.push(line);
+                    line = '';
+                }
+                if (character !== '\n') {
+                    line += character;
+                }
+            }
+            lines.push(line);
+        }
+        const captionHeight = lines.length ? 16 + lines.length * 22 : 0;
+        root.setAttribute('viewBox', `0 0 ${bounds.width} ${bounds.height + captionHeight}`);
+        SvgExporter.size(root, bounds.width, bounds.height + captionHeight);
+        SvgExporter.background(root, container);
+        lines.forEach((line, index) => {
+            const text = container.ownerDocument.createElementNS(SvgExporter.namespace, 'text');
+            text.setAttribute('data-role', 'scale-readout-label');
+            text.setAttribute('x', '16');
+            text.setAttribute('y', String(22 + index * 22));
+            text.setAttribute('fill', caption.color);
+            text.setAttribute('font-family', caption.fontFamily);
+            text.setAttribute('font-size', '14');
+            text.textContent = line;
+            root.appendChild(text);
+        });
+        for (const [index, axis] of axes.entries()) {
             const position = SvgExporter.bounds(axis);
             const copy = SvgExporter.copy(axis);
             copy.setAttribute('x', String(position.x - bounds.x));
-            copy.setAttribute('y', String(position.y - bounds.y));
+            copy.setAttribute('y', String(position.y - bounds.y + captionHeight));
             SvgExporter.size(copy, position.width, position.height);
+            customize?.(copy, index);
             root.appendChild(copy);
         }
         return SvgExporter.serialize(root);
     }
+    static background(root, source) {
+        const color = source.ownerDocument.defaultView.getComputedStyle(source).backgroundColor;
+        if (!color || color === 'transparent' || color === 'rgba(0, 0, 0, 0)') {
+            return;
+        }
+        const rect = source.ownerDocument.createElementNS(SvgExporter.namespace, 'rect');
+        rect.setAttribute('data-export-background', 'true');
+        rect.setAttribute('width', '100%');
+        rect.setAttribute('height', '100%');
+        rect.setAttribute('fill', color);
+        rect.setAttribute('stroke', 'none');
+        root.insertBefore(rect, root.firstChild);
+    }
     static bounds(element) {
         const bounds = element.getBoundingClientRect();
         if (!element.isConnected || bounds.width <= 0 || bounds.height <= 0) {

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

@@ -0,0 +1,36 @@
+import type { Complex } from '../math/Complex.js';
+import type { SmithScales } from '../scales/SmithScales.js';
+export interface ImageExportOptions {
+    /** Output pixels. Default: the snapshot dimensions. With only one dimension, preserve the complete image's aspect ratio. */
+    width?: number;
+    /** With both dimensions, center and fit the image without stretching or cropping. */
+    height?: number;
+    /** A concrete CSS color, or transparent. Omit to preserve configured SVG backgrounds. */
+    background?: string;
+}
+export interface ScaleExportReadout {
+    /** Use this reading instead of the live cursor/marker state; null exports empty scales. */
+    reflectionCoefficient: Complex | null;
+    /** Visible description of the reading, such as trace, marker, and frequency. */
+    label?: string;
+}
+export interface ScaleImageExportOptions extends ImageExportOptions {
+    readout?: ScaleExportReadout;
+}
+export type MarkerLegendField = 'frequency' | 'impedance' | 'admittance' | 'reflectionCoefficient' | 'vswr' | 'returnLoss';
+export interface MarkerLegendOptions {
+    /** Default: all markers of visible traces, in trace/marker order. Empty selects none. Unknown IDs throw. */
+    markerIds?: readonly string[];
+    /** Default: frequency and impedance. Empty keeps only the trace name and marker number. */
+    fields?: readonly MarkerLegendField[];
+}
+export interface SmithImageExportOptions extends ImageExportOptions {
+    /** Include a footer with the names and colors of visible traces. Default: false. */
+    legend?: boolean;
+    /** Include a marker legend below the chart/scales, independently of the trace legend. Default: false. */
+    markerLegend?: boolean | MarkerLegendOptions;
+    /** Include mounted radial scales centered below the chart, preserving their current layout/readings. */
+    scales?: SmithScales;
+    /** Override readings in the included radial scales without changing the live view. */
+    scaleReadout?: ScaleExportReadout;
+}

package/dist/lib/svg/export.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/traces/SmithMarker.js

@@ -53,8 +53,8 @@ export class SmithMarker extends SmithShape {
             .attr('pointer-events', 'none')
             .attr('aria-hidden', 'true');
         for (const [stroke, width] of [
-            ['white', 5],
-            ['#1d4ed8', 2.5],
+            ['var(--smithkit-marker-focusHaloColor)', 5],
+            ['var(--smithkit-marker-focusColor)', 2.5],
         ]) {
             this.focusRing
                 .append('circle')
@@ -63,17 +63,20 @@ export class SmithMarker extends SmithShape {
                 .attr('stroke-width', width)
                 .attr('vector-effect', 'non-scaling-stroke');
         }
-        this.triangle = g.append('polygon').attr('stroke', 'none').attr('fill', 'gray');
+        this.triangle = g
+            .append('polygon')
+            .attr('stroke', 'none')
+            .attr('fill', 'var(--smithkit-marker-outlineColor)');
         this.inner = g.append('polygon').attr('stroke', 'none').attr('fill', color);
         this.text = g
             .append('text')
             .attr('pointer-events', 'none')
             .attr('aria-hidden', 'true')
-            .attr('font-family', 'Verdana')
+            .attr('font-family', 'var(--smithkit-fontFamily)')
             .attr('font-weight', 'normal')
             .attr('text-anchor', 'middle')
             .attr('dominant-baseline', 'middle')
-            .attr('fill', 'white')
+            .attr('fill', 'var(--smithkit-marker-textColor)')
             .text(marker.toString());
         this.zoom(1);
         const drag = d3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-independent, interactive Smith chart library for JavaScript and TypeScript",
   "type": "module",
   "scripts": {