smithkit 0.1.0 → 0.2.0

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;
 }

package/dist/lib/traces/SmithMarker.js

@@ -0,0 +1,237 @@
+import * as d3 from 'd3';
+import { MouseGesture } from '../interaction/MouseGesture.js';
+import { SmithShape } from '../svg/SmithShape.js';
+import { SmithFormatter } from '../SmithFormatter.js';
+export class SmithMarker extends SmithShape {
+    dragStateHandler;
+    size = 18;
+    mouseGesture = new MouseGesture();
+    activeDrags = new Set();
+    destroyed = false;
+    sampleIndex = 0;
+    sampleCount = 1;
+    scale = 1;
+    triangle;
+    inner;
+    text;
+    hitArea;
+    focusRing;
+    rc = [0, 0];
+    dragHandler = null;
+    sampleHandler = null;
+    selectHandler = null;
+    constructor(marker, color, dragStateHandler = null) {
+        super(d3.select(document.createElementNS('http://www.w3.org/2000/svg', 'g')));
+        this.dragStateHandler = dragStateHandler;
+        const g = this.Element.attr('tabindex', 0)
+            .attr('role', 'slider')
+            .attr('aria-orientation', 'horizontal')
+            .attr('aria-description', 'Arrow keys move one sample; Shift+Arrow or Page Up/Down moves ten. Home and End select the first and last sample.')
+            .style('outline', 'none')
+            .style('touch-action', 'none')
+            .style('cursor', 'var(--smithkit-marker-cursor, grab)')
+            .on('focus.smithkit', () => {
+            this.focusRing.attr('visibility', null);
+            if (this.activeDrags.size === 0) {
+                this.selectHandler?.();
+            }
+        })
+            .on('blur.smithkit', () => this.focusRing.attr('visibility', 'hidden'))
+            .on('keydown.smithkit', (event) => this.keydown(event))
+            .on('touchstart.smithkit', (event) => event.stopPropagation());
+        this.hitArea = g
+            .append('circle')
+            .attr('class', 'marker-hit-area')
+            .attr('fill', 'none')
+            .attr('pointer-events', 'all')
+            .attr('stroke', 'none')
+            .attr('aria-hidden', 'true');
+        this.focusRing = g
+            .append('g')
+            .attr('class', 'marker-focus')
+            .attr('visibility', 'hidden')
+            .attr('pointer-events', 'none')
+            .attr('aria-hidden', 'true');
+        for (const [stroke, width] of [
+            ['white', 5],
+            ['#1d4ed8', 2.5],
+        ]) {
+            this.focusRing
+                .append('circle')
+                .attr('fill', 'none')
+                .attr('stroke', stroke)
+                .attr('stroke-width', width)
+                .attr('vector-effect', 'non-scaling-stroke');
+        }
+        this.triangle = g.append('polygon').attr('stroke', 'none').attr('fill', 'gray');
+        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-weight', 'normal')
+            .attr('text-anchor', 'middle')
+            .attr('dominant-baseline', 'middle')
+            .attr('fill', 'white')
+            .text(marker.toString());
+        this.zoom(1);
+        const drag = d3
+            .drag()
+            .container(() => this.Node.parentNode)
+            .touchable(() => true)
+            .filter((event) => !this.destroyed && !event.ctrlKey && !event.button && this.activeDrags.size === 0)
+            .on('start', (event) => {
+            if (this.destroyed || this.activeDrags.size > 0) {
+                return;
+            }
+            this.mouseGesture.capture(event.sourceEvent, 'drag');
+            const wasIdle = this.activeDrags.size === 0;
+            this.activeDrags.add(event.identifier);
+            this.Node.focus({ preventScroll: true });
+            if (wasIdle) {
+                this.dragStateHandler?.(true);
+                this.selectHandler?.();
+            }
+        })
+            .on('drag', (event) => {
+            if (!this.destroyed && this.activeDrags.has(event.identifier)) {
+                this.dragHandler?.([event.x, event.y]);
+            }
+        })
+            .on('end', (event) => {
+            if (this.activeDrags.delete(event.identifier) && this.activeDrags.size === 0) {
+                this.dragStateHandler?.(false);
+            }
+        });
+        g.call(drag);
+    }
+    focus() {
+        if (this.destroyed || this.Element.style('display') === 'none' || !this.Node.isConnected) {
+            return false;
+        }
+        this.Node.focus({ preventScroll: true });
+        return this.Node.ownerDocument.activeElement === this.Node;
+    }
+    setReading(name, index, count, frequencyHz) {
+        this.sampleIndex = index;
+        this.sampleCount = count;
+        this.Element.attr('aria-label', name)
+            .attr('aria-valuemin', 0)
+            .attr('aria-valuemax', count - 1)
+            .attr('aria-valuenow', index)
+            .attr('aria-valuetext', `${SmithFormatter.number(frequencyHz)}Hz, sample ${index + 1} of ${count}`)
+            .attr('aria-disabled', count <= 1 ? 'true' : null);
+    }
+    keydown(event) {
+        if (this.destroyed ||
+            event.altKey ||
+            event.ctrlKey ||
+            event.metaKey ||
+            this.activeDrags.size > 0) {
+            return;
+        }
+        const step = event.shiftKey ? 10 : 1;
+        let next;
+        switch (event.key) {
+            case 'ArrowRight':
+            case 'ArrowUp':
+                next = this.sampleIndex + step;
+                break;
+            case 'ArrowLeft':
+            case 'ArrowDown':
+                next = this.sampleIndex - step;
+                break;
+            case 'PageUp':
+                next = this.sampleIndex + 10;
+                break;
+            case 'PageDown':
+                next = this.sampleIndex - 10;
+                break;
+            case 'Home':
+                next = 0;
+                break;
+            case 'End':
+                next = this.sampleCount - 1;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        this.selectHandler?.();
+        next = Math.max(0, Math.min(this.sampleCount - 1, next));
+        if (next !== this.sampleIndex) {
+            this.sampleHandler?.(next);
+        }
+    }
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
+        this.dragHandler = null;
+        this.sampleHandler = null;
+        this.selectHandler = null;
+        this.cancelDrag();
+        this.dragStateHandler = null;
+        this.Element.on('.drag', null).on('.smithkit', null).interrupt();
+        this.Element.selectAll('*').on('.drag', null).interrupt();
+        this.Element.remove();
+    }
+    cancelDrag() {
+        if (this.activeDrags.size > 0) {
+            this.activeDrags.clear();
+            this.dragStateHandler?.(false);
+        }
+        this.mouseGesture.destroy();
+    }
+    setColor(color) {
+        this.inner.attr('fill', color);
+    }
+    get Position() {
+        return this.rc;
+    }
+    move(p) {
+        this.rc = p;
+        this.triangle.attr('transform', `translate(${p[0]},${p[1]})`);
+        this.inner.attr('transform', `translate(${p[0]},${p[1]})`);
+        this.text.attr('x', p[0]).attr('y', p[1]);
+        const centerY = p[1] - this.size / this.scale / 2;
+        this.hitArea.attr('cx', p[0]).attr('cy', centerY);
+        this.focusRing.selectAll('circle').attr('cx', p[0]).attr('cy', centerY);
+    }
+    zoom(k) {
+        if (!Number.isFinite(k) || k <= 0) {
+            return;
+        }
+        this.scale = k;
+        const size = this.size / k;
+        const h = size / 12;
+        const alpha = Math.atan(1 / 2);
+        const beta = Math.PI / 2 - alpha;
+        const x = h / Math.sin(alpha);
+        const y = h / Math.sin(beta) + h / Math.tan(beta);
+        this.triangle.attr('points', `0,0 ${size / 2},${-size} ${-size / 2},${-size}`);
+        this.inner.attr('points', `0,${-x} ${size / 2 - y},${-size + h} ${-size / 2 + y},${-size + h}`);
+        this.text.attr('font-size', size / 1.8).attr('dy', -size / 1.6);
+        this.hitArea.attr('r', 22 / k);
+        this.focusRing.selectAll('circle').attr('r', 15 / k);
+        this.move(this.rc);
+    }
+    show() {
+        this.Element.attr('opacity', null);
+    }
+    hide() {
+        this.Element.attr('opacity', '0');
+    }
+    setDragHandler(handler) {
+        this.dragHandler = handler;
+    }
+    setSampleHandler(handler) {
+        this.sampleHandler = handler;
+    }
+    setSelectHandler(handler) {
+        this.selectHandler = handler;
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { MarkerSelectionStrategy } from '../measurements.js';
+import type { Point } from '../math/geometry.js';
+import type { TraceSample, TraceSamples } from '../samples.js';
+export interface TraceMarker {
+    readonly number: number;
+    selectedPoint: TraceSample;
+}
+/** Owns validated samples and marker selections without depending on SVG or D3. */
+export declare class TraceModel {
+    private samples;
+    private markers;
+    private markerCount;
+    constructor(samples: TraceSamples);
+    get Samples(): TraceSamples;
+    get Markers(): readonly TraceMarker[];
+    addMarker(sampleIndex: number): TraceMarker;
+    removeMarker(index: number): TraceMarker | undefined;
+    getMarker(index: number): TraceMarker | undefined;
+    markerIndex(marker: TraceMarker): number;
+    markerSampleIndex(index: number): number;
+    setMarkerSample(index: number, sampleIndex: number): TraceMarker | undefined;
+    setMarkerFrequency(index: number, frequencyHz: number): TraceMarker | undefined;
+    /** Returns false when dragging still selects the same sample. */
+    selectNearestPoint(marker: TraceMarker, point: Readonly<Point>): boolean;
+    update(values: TraceSamples, strategy: MarkerSelectionStrategy): void;
+    clear(): void;
+    private nearestFrequencyIndex;
+    private nearestPoint;
+    private validateSampleIndex;
+    private copySamples;
+}

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;
+}