smithkit 0.1.1 → 0.2.0

package/dist/lib/traces/TraceModel.js

@@ -0,0 +1,123 @@
+/** Owns validated samples and marker selections without depending on SVG or D3. */
+export class TraceModel {
+    samples;
+    markers = [];
+    markerCount = 0;
+    constructor(samples) {
+        this.samples = this.copySamples(samples);
+    }
+    get Samples() {
+        return this.samples;
+    }
+    get Markers() {
+        return this.markers.slice();
+    }
+    addMarker(sampleIndex) {
+        this.validateSampleIndex(sampleIndex);
+        const marker = { number: ++this.markerCount, selectedPoint: this.samples[sampleIndex] };
+        this.markers.push(marker);
+        return marker;
+    }
+    removeMarker(index) {
+        const marker = this.markers[index];
+        if (marker) {
+            this.markers.splice(index, 1);
+        }
+        return marker;
+    }
+    getMarker(index) {
+        return this.markers[index];
+    }
+    markerIndex(marker) {
+        return this.markers.indexOf(marker);
+    }
+    markerSampleIndex(index) {
+        const marker = this.markers[index];
+        return marker ? this.samples.indexOf(marker.selectedPoint) : -1;
+    }
+    setMarkerSample(index, sampleIndex) {
+        const marker = this.markers[index];
+        if (!marker) {
+            return;
+        }
+        this.validateSampleIndex(sampleIndex);
+        marker.selectedPoint = this.samples[sampleIndex];
+        return marker;
+    }
+    setMarkerFrequency(index, frequencyHz) {
+        if (!this.markers[index]) {
+            return;
+        }
+        if (!Number.isFinite(frequencyHz) || frequencyHz < 0) {
+            throw new RangeError('Marker frequency must be finite and non-negative.');
+        }
+        return this.setMarkerSample(index, this.nearestFrequencyIndex(frequencyHz));
+    }
+    /** Returns false when dragging still selects the same sample. */
+    selectNearestPoint(marker, point) {
+        if (!this.markers.includes(marker)) {
+            return false;
+        }
+        const sample = this.nearestPoint(point);
+        if (sample === marker.selectedPoint) {
+            return false;
+        }
+        marker.selectedPoint = sample;
+        return true;
+    }
+    update(values, strategy) {
+        // Validate and copy before mutating either samples or marker selections.
+        const samples = this.copySamples(values);
+        const selectedIndices = this.markers.map((entry) => this.samples.indexOf(entry.selectedPoint));
+        this.samples = samples;
+        this.markers.forEach((entry, index) => {
+            if (strategy === 'sample-index') {
+                entry.selectedPoint = samples[Math.min(selectedIndices[index], samples.length - 1)];
+            }
+            else if (strategy === 'reflection') {
+                entry.selectedPoint = this.nearestPoint(entry.selectedPoint.reflectionCoefficient);
+            }
+            else {
+                entry.selectedPoint = samples[this.nearestFrequencyIndex(entry.selectedPoint.frequencyHz)];
+            }
+        });
+    }
+    clear() {
+        this.samples = [];
+        this.markers = [];
+    }
+    nearestFrequencyIndex(frequencyHz) {
+        let closest = 0;
+        let distance = Math.abs(this.samples[0].frequencyHz - frequencyHz);
+        for (let i = 1; i < this.samples.length; i++) {
+            const nextDistance = Math.abs(this.samples[i].frequencyHz - frequencyHz);
+            if (nextDistance < distance) {
+                closest = i;
+                distance = nextDistance;
+            }
+        }
+        return closest;
+    }
+    nearestPoint(point) {
+        const distance = (sample) => Math.hypot(point[0] - sample.reflectionCoefficient[0], point[1] - sample.reflectionCoefficient[1]);
+        return this.samples.reduce((previous, current) => distance(previous) <= distance(current) ? previous : current);
+    }
+    validateSampleIndex(index) {
+        if (!Number.isInteger(index) || index < 0 || index >= this.samples.length) {
+            throw new RangeError('Sample index is outside this trace.');
+        }
+    }
+    copySamples(values) {
+        if (!values.length ||
+            values.some(({ frequencyHz, reflectionCoefficient }) => !Number.isFinite(frequencyHz) ||
+                frequencyHz < 0 ||
+                reflectionCoefficient.length !== 2 ||
+                !reflectionCoefficient.every(Number.isFinite))) {
+            throw new RangeError('A dataset requires samples with a non-negative finite frequency and two finite coordinates.');
+        }
+        return values.map(({ frequencyHz, reflectionCoefficient }) => ({
+            frequencyHz,
+            reflectionCoefficient: [reflectionCoefficient[0], reflectionCoefficient[1]],
+        }));
+    }
+}

package/dist/lib/traces/TraceRenderer.d.ts

@@ -0,0 +1,33 @@
+import { SmithGroup } from '../svg/SmithGroup.js';
+import { SmithScaler } from '../svg/SmithScaler.js';
+import type { TraceStyle } from '../measurements.js';
+import type { TraceSamples } from '../samples.js';
+export interface TraceTransform {
+    x: number;
+    y: number;
+    k: number;
+}
+/** Draws a trace; sample validation and marker selection belong to TraceModel. */
+export declare class TraceRenderer {
+    private data;
+    private color;
+    private transform;
+    private scaler;
+    private style;
+    private viewportScale;
+    private visible;
+    private group;
+    constructor(data: TraceSamples, color: string, transform: TraceTransform, container: SmithGroup, scaler: SmithScaler, style?: Partial<TraceStyle>);
+    private drawTrace;
+    private renderPoints;
+    setViewportScale(scale: number): void;
+    zoom(transform: TraceTransform): void;
+    private zoomDataPoints;
+    setColor(color: string): void;
+    get Style(): TraceStyle;
+    setStyle(options: Partial<TraceStyle>): void;
+    private redraw;
+    setVisible(visible: boolean): void;
+    update(data: TraceSamples): void;
+    destroy(): void;
+}

package/dist/lib/traces/TraceRenderer.js

@@ -0,0 +1,152 @@
+import { line } from 'd3';
+import { SmithGroup } from '../svg/SmithGroup.js';
+/** Draws a trace; sample validation and marker selection belong to TraceModel. */
+export class TraceRenderer {
+    data;
+    color;
+    transform;
+    scaler;
+    style;
+    viewportScale = 1;
+    visible = true;
+    group;
+    constructor(data, color, transform, container, scaler, style = {}) {
+        this.data = data;
+        this.color = color;
+        this.transform = transform;
+        this.scaler = scaler;
+        this.style = {
+            mode: style.mode ?? 'points',
+            lineWidth: style.lineWidth ?? 2,
+            pointRadius: style.pointRadius ?? 2,
+        };
+        this.group = this.drawTrace(data).attr('pointer-events', 'none');
+        container.append(this.group);
+    }
+    drawTrace(data) {
+        const group = new SmithGroup({
+            stroke: 'none',
+            strokeWidth: 'none',
+            fill: this.color,
+        });
+        group.attr('data-role', 'samples');
+        group.attr('data-mode', this.style.mode);
+        if (this.style.mode !== 'points') {
+            const path = line()
+                .x((sample) => this.scaler.x(sample.reflectionCoefficient[0]))
+                .y((sample) => this.scaler.y(sample.reflectionCoefficient[1]));
+            group.Element.append('path')
+                .attr('class', 'trace-line')
+                .attr('d', path(data))
+                .attr('fill', 'none')
+                .attr('stroke', this.color)
+                .attr('stroke-width', this.style.lineWidth)
+                .attr('vector-effect', 'non-scaling-stroke')
+                .attr('stroke-linejoin', 'round')
+                .attr('stroke-linecap', 'round');
+        }
+        if (this.style.mode !== 'line') {
+            this.renderPoints(group, data);
+        }
+        return group;
+    }
+    renderPoints(group, data) {
+        let visible = data;
+        if (data.length > 5000) {
+            const cells = new Set();
+            const cellSize = Math.max(0.5, this.style.pointRadius) / this.viewportScale;
+            const extent = this.scaler.x(1);
+            const margin = this.style.pointRadius / this.viewportScale;
+            visible = data.filter((sample) => {
+                const x = this.scaler.x(sample.reflectionCoefficient[0]) * this.transform.k + this.transform.x;
+                const y = this.scaler.y(sample.reflectionCoefficient[1]) * this.transform.k + this.transform.y;
+                if (x < -margin || y < -margin || x > extent + margin || y > extent + margin) {
+                    return false;
+                }
+                const cell = `${Math.floor(x / cellSize)},${Math.floor(y / cellSize)}`;
+                if (cells.has(cell)) {
+                    return false;
+                }
+                cells.add(cell);
+                return true;
+            });
+        }
+        group.Element.selectAll('circle')
+            .data(visible)
+            .join('circle')
+            .attr('cx', (sample) => this.scaler.x(sample.reflectionCoefficient[0]))
+            .attr('cy', (sample) => this.scaler.y(sample.reflectionCoefficient[1]))
+            .attr('r', this.style.pointRadius / (this.transform.k * this.viewportScale));
+    }
+    setViewportScale(scale) {
+        if (scale === this.viewportScale || !Number.isFinite(scale) || scale <= 0) {
+            return;
+        }
+        this.viewportScale = scale;
+        this.zoomDataPoints();
+    }
+    zoom(transform) {
+        this.transform = transform;
+        this.zoomDataPoints();
+    }
+    zoomDataPoints() {
+        const k = this.transform.k;
+        if (this.style.mode === 'line') {
+            return;
+        }
+        if (this.data.length > 5000) {
+            this.renderPoints(this.group, this.data);
+        }
+        else {
+            this.group.Element.selectAll('circle').attr('r', this.style.pointRadius / (k * this.viewportScale));
+        }
+    }
+    setColor(color) {
+        this.color = color;
+        this.group.attr('fill', color);
+        this.group.Element.select('.trace-line').attr('stroke', color);
+    }
+    get Style() {
+        return { ...this.style };
+    }
+    setStyle(options) {
+        const next = {
+            mode: options.mode ?? this.style.mode,
+            lineWidth: options.lineWidth ?? this.style.lineWidth,
+            pointRadius: options.pointRadius ?? this.style.pointRadius,
+        };
+        if (next.mode === this.style.mode &&
+            next.lineWidth === this.style.lineWidth &&
+            next.pointRadius === this.style.pointRadius) {
+            return;
+        }
+        const modeChanged = next.mode !== this.style.mode;
+        this.style = next;
+        if (modeChanged) {
+            this.redraw();
+        }
+        else {
+            this.group.Element.select('.trace-line').attr('stroke-width', next.lineWidth);
+            this.zoomDataPoints();
+        }
+    }
+    redraw() {
+        const group = this.drawTrace(this.data).attr('pointer-events', 'none');
+        // Replace in place to retain trace ordering beneath the separate marker layer.
+        this.group.Node.replaceWith(group.Node);
+        this.group = group;
+        this.group.Element.style('display', () => (this.visible ? null : 'none'));
+    }
+    setVisible(visible) {
+        this.visible = visible;
+        this.group.Element.style('display', () => (visible ? null : 'none'));
+    }
+    update(data) {
+        this.data = data;
+        this.redraw();
+    }
+    destroy() {
+        this.data = [];
+        this.group.Element.remove();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithkit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Framework-independent, interactive Smith chart library for JavaScript and TypeScript",
   "type": "module",
   "scripts": {
@@ -31,10 +31,13 @@
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.63.0",
     "@types/node": "^24.0.0",
+    "@types/pngjs": "^6.0.5",
     "@typescript/native": "npm:typescript@^7.0.2",
     "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.13.0",
+    "pixelmatch": "^8.0.0",
+    "pngjs": "^7.0.0",
     "prettier": "3.9.9",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.71.0",

package/dist/lib/SmithArcsDefs.d.ts

@@ -1,10 +0,0 @@
-import { createGridDefinitions } from './grid/definitions.js';
-import { resistanceLabels, reactanceLabels } from './grid/labels.js';
-export { SmithArcEntry } from './grid/types.js';
-export type { SmithArcDef, SmithTickDef, SmithTicksShapes, SmithTicksData } from './grid/types.js';
-export declare class SmithArcsDefs {
-    private constructor();
-    static getData: typeof createGridDefinitions;
-    static resistanceLabels: typeof resistanceLabels;
-    static reactanceLabels: typeof reactanceLabels;
-}

package/dist/lib/SmithArcsDefs.js

@@ -1,10 +0,0 @@
-import { createGridDefinitions } from './grid/definitions.js';
-import { resistanceLabels, reactanceLabels } from './grid/labels.js';
-// Compatibility facade; definitions and label rules are independent of SVG rendering.
-export { SmithArcEntry } from './grid/types.js';
-export class SmithArcsDefs {
-    constructor() { }
-    static getData = createGridDefinitions;
-    static resistanceLabels = resistanceLabels;
-    static reactanceLabels = reactanceLabels;
-}

package/dist/lib/components.d.ts

@@ -1,14 +0,0 @@
-/** An ideal series component equivalent to a reactance at one frequency. */
-export type ReactiveComponent = {
-    readonly kind: 'inductor';
-    readonly inductanceHenries: number;
-} | {
-    readonly kind: 'capacitor';
-    readonly capacitanceFarads: number;
-};
-/**
- * Convert reactance in ohms at a frequency in Hz to an ideal series L or C.
- * Zero frequency, zero reactance, or an unrepresentable component returns undefined.
- * Non-finite reactance and negative/non-finite frequency throw RangeError.
- */
-export declare function reactanceToComponent(reactanceOhms: number, frequencyHz: number): ReactiveComponent | undefined;

package/dist/lib/components.js

@@ -1,26 +0,0 @@
-/**
- * Convert reactance in ohms at a frequency in Hz to an ideal series L or C.
- * Zero frequency, zero reactance, or an unrepresentable component returns undefined.
- * Non-finite reactance and negative/non-finite frequency throw RangeError.
- */
-export function reactanceToComponent(reactanceOhms, frequencyHz) {
-    if (!Number.isFinite(reactanceOhms)) {
-        throw new RangeError('Reactance must be finite.');
-    }
-    if (!Number.isFinite(frequencyHz) || frequencyHz < 0) {
-        throw new RangeError('Frequency must be finite and non-negative.');
-    }
-    if (frequencyHz === 0 || reactanceOhms === 0) {
-        return;
-    }
-    // Compute in log space so intermediate products/quotients cannot overflow.
-    const logReactance = Math.log(Math.abs(reactanceOhms));
-    const logAngularFrequency = Math.log(2 * Math.PI) + Math.log(frequencyHz);
-    const value = Math.exp((reactanceOhms > 0 ? logReactance : -logReactance) - logAngularFrequency);
-    if (!Number.isFinite(value) || value === 0) {
-        return;
-    }
-    return reactanceOhms > 0
-        ? { kind: 'inductor', inductanceHenries: value }
-        : { kind: 'capacitor', capacitanceFarads: value };
-}