smithkit 0.1.1 → 0.3.0

package/dist/lib/svg/SvgExporter.js

@@ -0,0 +1,182 @@
+/** Captures rendered SVG with presentation styles resolved in its source document. */
+export class SvgExporter {
+    constructor() { }
+    static namespace = 'http://www.w3.org/2000/svg';
+    static properties = [
+        'color',
+        'display',
+        'visibility',
+        'opacity',
+        'fill',
+        'fill-opacity',
+        'fill-rule',
+        'stroke',
+        'stroke-width',
+        'stroke-opacity',
+        'stroke-dasharray',
+        'stroke-dashoffset',
+        'stroke-linecap',
+        'stroke-linejoin',
+        'stroke-miterlimit',
+        'vector-effect',
+        'paint-order',
+        'shape-rendering',
+        'text-rendering',
+        'font-family',
+        'font-size',
+        'font-style',
+        'font-weight',
+        'font-variant',
+        'font-stretch',
+        'letter-spacing',
+        'word-spacing',
+        'text-anchor',
+        'dominant-baseline',
+        'alignment-baseline',
+        'baseline-shift',
+        'text-decoration',
+        'white-space',
+    ];
+    static nonInherited = new Set([
+        'display',
+        'opacity',
+        'vector-effect',
+        'alignment-baseline',
+        'dominant-baseline',
+        'baseline-shift',
+        'text-decoration',
+    ]);
+    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, customize, caption) {
+        const bounds = SvgExporter.bounds(container);
+        const root = container.ownerDocument.createElementNS(SvgExporter.namespace, 'svg');
+        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 + 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) {
+            throw new Error('SVG export requires a mounted component with a visible, non-zero size.');
+        }
+        return bounds;
+    }
+    static copy(source) {
+        const copy = source.cloneNode(true);
+        const originals = [source, ...source.querySelectorAll('*')];
+        const copies = [copy, ...copy.querySelectorAll('*')];
+        const view = source.ownerDocument.defaultView;
+        const styles = new Map(originals.map((element) => [element, view.getComputedStyle(element)]));
+        originals.forEach((original, index) => {
+            const element = copies[index];
+            const style = styles.get(original);
+            const parentStyle = original.parentElement ? styles.get(original.parentElement) : undefined;
+            // Keep SVG geometry/transform attributes, but replace page-dependent CSS.
+            element.removeAttribute('style');
+            for (const property of SvgExporter.properties) {
+                const value = style.getPropertyValue(property);
+                element.removeAttribute(property);
+                // Resolve inherited values at their boundary instead of repeating every font and
+                // stroke property on thousands of descendants. CSS overrides may replace attributes.
+                if (value &&
+                    (SvgExporter.nonInherited.has(property) ||
+                        parentStyle?.getPropertyValue(property) !== value)) {
+                    element.style.setProperty(property, value);
+                }
+            }
+            // An exported image has no event handlers or interactive controls.
+            element.removeAttribute('tabindex');
+            if (original.getAttribute('data-role') === 'marker') {
+                // A static marker is an image, not an operable sample slider.
+                element.setAttribute('role', 'img');
+                element.setAttribute('aria-label', `${original.getAttribute('aria-label')}; ${original.getAttribute('aria-valuetext')}`);
+                for (const attribute of [
+                    'aria-valuemin',
+                    'aria-valuemax',
+                    'aria-valuenow',
+                    'aria-valuetext',
+                    'aria-orientation',
+                    'aria-description',
+                    'aria-disabled',
+                ]) {
+                    element.removeAttribute(attribute);
+                }
+            }
+            element.removeAttribute('class');
+            for (const attribute of [...element.attributes]) {
+                if (attribute.name.startsWith('on')) {
+                    element.removeAttribute(attribute.name);
+                }
+            }
+        });
+        return copy;
+    }
+    static size(svg, width, height) {
+        svg.setAttribute('width', String(width));
+        svg.setAttribute('height', String(height));
+        svg.style.setProperty('overflow', 'hidden');
+    }
+    static serialize(svg) {
+        svg.setAttribute('xmlns', SvgExporter.namespace);
+        return new XMLSerializer().serializeToString(svg);
+    }
+}

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/{draw → traces}/SmithData.d.ts

@@ -1,48 +1,33 @@
-import { SmithGroup } from './SmithGroup.js';
+import { SmithGroup } from '../svg/SmithGroup.js';
 import type { TraceStyle, MarkerSelectionStrategy } from '../measurements.js';
 import { SmithMarker } from './SmithMarker.js';
-import { SmithScaler } from './SmithScaler.js';
-import { TraceSamples, TraceSample } from '../samples.js';
-interface Marker {
-    marker: SmithMarker;
-    selectedPoint: TraceSample;
-    number: number;
-}
-interface Transform {
-    x: number;
-    y: number;
-    k: number;
-}
+import { SmithScaler } from '../svg/SmithScaler.js';
+import type { TraceSamples, TraceSample } from '../samples.js';
+import { type TraceTransform } from './TraceRenderer.js';
+/** Coordinates trace rendering, draggable markers, and deferred marker events. */
 export declare class SmithData {
-    private data;
     private color;
     private transform;
-    private fgContainer;
     private scaler;
     private markerDragHandler?;
     private markerContainer;
-    private style;
-    private viewportScale;
+    private readonly model;
+    private readonly renderer;
+    private readonly markers;
+    private readonly pendingEvents;
     private destroyed;
+    private viewportScale;
+    private name;
+    private selectHandler;
     private visible;
-    private pendingEvents;
-    private group;
-    private markersCount;
-    private markers;
     private handler;
-    constructor(data: TraceSamples, color: string, transform: Transform, fgContainer: SmithGroup, scaler: SmithScaler, markerDragHandler?: ((marker: SmithMarker, dragging: boolean) => void) | undefined, markerContainer?: SmithGroup, style?: Partial<TraceStyle>);
-    private drawTrace;
-    private renderPoints;
+    constructor(data: TraceSamples, color: string, transform: TraceTransform, container: SmithGroup, scaler: SmithScaler, markerDragHandler?: ((marker: SmithMarker, dragging: boolean) => void) | undefined, markerContainer?: SmithGroup, style?: Partial<TraceStyle>);
     setViewportScale(scale: number): void;
-    zoom(transform: Transform): void;
-    private zoomDataPoints;
-    private zoomAllMarkers;
+    zoom(transform: TraceTransform): void;
     addMarker(sampleIndex?: number): number;
     removeMarker(index: number): boolean;
     setMarkerSample(index: number, sampleIndex: number): boolean;
     setMarkerFrequency(index: number, frequencyHz: number): boolean;
-    private nearestFrequencyIndex;
-    private validateSampleIndex;
     get Samples(): TraceSamples;
     get SampleCount(): number;
     get Color(): string;
@@ -51,16 +36,20 @@ export declare class SmithData {
     setColor(color: string): void;
     get Style(): TraceStyle;
     setStyle(options: Partial<TraceStyle>): void;
-    private redraw;
     setVisible(visible: boolean): void;
-    private copySamples;
+    private moveMarker;
+    private updateReading;
+    setName(name: string): void;
+    setMarkerSelectHandler(handler: (marker: SmithMarker) => void): void;
     private notifyMarker;
     private cancelEvents;
     update(values: TraceSamples, strategy?: MarkerSelectionStrategy): void;
     destroy(): void;
-    getMarker(index: number): Marker | undefined;
-    get Markers(): Marker[];
+    get Markers(): {
+        number: number;
+        selectedPoint: TraceSample;
+        marker: SmithMarker;
+    }[];
     setMarkerMoveHandler(handler: (marker: number, data: TraceSample) => void): void;
-    private findClosestPointTo;
+    private assertAlive;
 }
-export {};

package/dist/lib/traces/SmithData.js

@@ -0,0 +1,195 @@
+import { SmithMarker } from './SmithMarker.js';
+import { TraceModel } from './TraceModel.js';
+import { TraceRenderer } from './TraceRenderer.js';
+/** Coordinates trace rendering, draggable markers, and deferred marker events. */
+export class SmithData {
+    color;
+    transform;
+    scaler;
+    markerDragHandler;
+    markerContainer;
+    model;
+    renderer;
+    markers = new Map();
+    pendingEvents = new Map();
+    destroyed = false;
+    viewportScale = 1;
+    name = 'Trace';
+    selectHandler = null;
+    visible = true;
+    handler = null;
+    constructor(data, color, transform, container, scaler, markerDragHandler, markerContainer = container, style = {}) {
+        this.color = color;
+        this.transform = transform;
+        this.scaler = scaler;
+        this.markerDragHandler = markerDragHandler;
+        this.markerContainer = markerContainer;
+        this.model = new TraceModel(data);
+        this.renderer = new TraceRenderer(this.model.Samples, color, transform, container, scaler, style);
+    }
+    setViewportScale(scale) {
+        this.viewportScale = scale;
+        this.renderer.setViewportScale(scale);
+        this.markers.forEach((marker) => marker.zoom(this.transform.k * scale));
+    }
+    zoom(transform) {
+        if (this.destroyed) {
+            return;
+        }
+        this.transform = transform;
+        this.renderer.zoom(transform);
+        this.markers.forEach((marker) => marker.zoom(transform.k * this.viewportScale));
+    }
+    addMarker(sampleIndex = 0) {
+        this.assertAlive();
+        const entry = this.model.addMarker(sampleIndex);
+        const marker = new SmithMarker(entry.number, this.color, (dragging) => this.markerDragHandler?.(marker, dragging));
+        this.markers.set(entry, marker);
+        marker.Element.attr('data-role', 'marker');
+        marker.setSampleHandler((sampleIndex) => this.setMarkerSample(this.model.markerIndex(entry), sampleIndex));
+        marker.setSelectHandler(() => this.selectHandler?.(marker));
+        this.markerContainer.append(marker);
+        marker.setDragHandler((point) => {
+            if (this.model.selectNearestPoint(entry, this.scaler.pointInvert(point))) {
+                this.moveMarker(entry);
+                marker.zoom(this.transform.k * this.viewportScale);
+            }
+        });
+        marker.zoom(this.transform.k * this.viewportScale);
+        marker.show();
+        marker.Element.style('display', () => (this.visible ? null : 'none'));
+        this.moveMarker(entry);
+        return this.model.markerIndex(entry);
+    }
+    removeMarker(index) {
+        const entry = this.model.getMarker(index);
+        if (!entry) {
+            return false;
+        }
+        clearTimeout(this.pendingEvents.get(entry));
+        this.pendingEvents.delete(entry);
+        // Ending a drag must still be able to read the marker snapshot.
+        this.markers.get(entry).destroy();
+        this.markers.delete(entry);
+        this.model.removeMarker(index);
+        return true;
+    }
+    setMarkerSample(index, sampleIndex) {
+        const entry = this.model.setMarkerSample(index, sampleIndex);
+        if (!entry) {
+            return false;
+        }
+        this.moveMarker(entry);
+        return true;
+    }
+    setMarkerFrequency(index, frequencyHz) {
+        const entry = this.model.setMarkerFrequency(index, frequencyHz);
+        if (!entry) {
+            return false;
+        }
+        this.moveMarker(entry);
+        return true;
+    }
+    get Samples() {
+        return this.model.Samples;
+    }
+    get SampleCount() {
+        return this.model.Samples.length;
+    }
+    get Color() {
+        return this.color;
+    }
+    get Visible() {
+        return this.visible;
+    }
+    markerSampleIndex(index) {
+        return this.model.markerSampleIndex(index);
+    }
+    setColor(color) {
+        this.color = color;
+        this.renderer.setColor(color);
+        this.markers.forEach((marker) => marker.setColor(color));
+    }
+    get Style() {
+        return this.renderer.Style;
+    }
+    setStyle(options) {
+        this.renderer.setStyle(options);
+    }
+    setVisible(visible) {
+        this.visible = visible;
+        this.renderer.setVisible(visible);
+        this.markers.forEach((marker) => {
+            if (!visible) {
+                marker.cancelDrag();
+                marker.Node?.blur();
+            }
+            marker.Element.style('display', () => (visible ? null : 'none'));
+        });
+    }
+    moveMarker(entry) {
+        const marker = this.markers.get(entry);
+        marker.move(this.scaler.point(entry.selectedPoint.reflectionCoefficient));
+        this.updateReading(entry, marker);
+        this.notifyMarker(entry);
+    }
+    updateReading(entry, marker) {
+        marker.setReading(`${this.name}, marker ${entry.number}`, this.model.markerSampleIndex(this.model.markerIndex(entry)), this.SampleCount, entry.selectedPoint.frequencyHz);
+    }
+    setName(name) {
+        this.name = name;
+        this.markers.forEach((marker, entry) => this.updateReading(entry, marker));
+    }
+    setMarkerSelectHandler(handler) {
+        this.selectHandler = handler;
+    }
+    notifyMarker(entry) {
+        if (this.pendingEvents.has(entry)) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.pendingEvents.delete(entry);
+            const index = this.model.markerIndex(entry);
+            if (!this.destroyed && index >= 0) {
+                this.handler?.(index, entry.selectedPoint);
+            }
+        }, 0);
+        this.pendingEvents.set(entry, timer);
+    }
+    cancelEvents() {
+        this.pendingEvents.forEach((timer) => clearTimeout(timer));
+        this.pendingEvents.clear();
+    }
+    update(values, strategy = 'frequency') {
+        this.assertAlive();
+        this.model.update(values, strategy);
+        this.cancelEvents();
+        this.renderer.update(this.model.Samples);
+        this.model.Markers.forEach((entry) => this.moveMarker(entry));
+    }
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
+        this.cancelEvents();
+        this.handler = null;
+        this.selectHandler = null;
+        this.markers.forEach((marker) => marker.destroy());
+        this.markers.clear();
+        this.model.clear();
+        this.markerDragHandler = undefined;
+        this.renderer.destroy();
+    }
+    get Markers() {
+        return this.model.Markers.map((entry) => ({ ...entry, marker: this.markers.get(entry) }));
+    }
+    setMarkerMoveHandler(handler) {
+        this.handler = handler;
+    }
+    assertAlive() {
+        if (this.destroyed) {
+            throw new Error('This dataset has been removed.');
+        }
+    }
+}

package/dist/lib/{draw → traces}/SmithMarker.d.ts

@@ -1,25 +1,36 @@
-import { SmithShape } from './SmithShape.js';
-import { Point } from '../shapes/Point.js';
+import { SmithShape } from '../svg/SmithShape.js';
+import { Point } from '../math/geometry.js';
 export declare class SmithMarker extends SmithShape {
     private dragStateHandler;
     private readonly size;
     private mouseGesture;
     private activeDrags;
     private destroyed;
+    private sampleIndex;
+    private sampleCount;
+    private scale;
     private triangle;
     private inner;
     private text;
+    private hitArea;
+    private focusRing;
     private rc;
     private dragHandler;
+    private sampleHandler;
+    private selectHandler;
     constructor(marker: number, color: string, dragStateHandler?: ((dragging: boolean) => void) | null);
+    focus(): boolean;
+    setReading(name: string, index: number, count: number, frequencyHz: number): void;
+    private keydown;
     destroy(): void;
     cancelDrag(): void;
     setColor(color: string): void;
-    private onDrag;
     get Position(): Point;
     move(p: Point): void;
     zoom(k: number): void;
     show(): void;
     hide(): void;
     setDragHandler(handler: (p: Point) => void): void;
+    setSampleHandler(handler: (index: number) => void): void;
+    setSelectHandler(handler: () => void): void;
 }