smithkit 0.1.0 → 0.2.0

package/README.md

@@ -5,44 +5,35 @@ interactive SVG Smith charts, RF calculations, and S11 measurement exploration.
 
 [Try the interactive demo](https://rosek86.github.io/smithkit/).
 
+Upgrading from 0.1.x? Version 0.2.0 groups calculation, parsing, formatting, and
+comparison functions into classes. See the [migration guide](https://github.com/rosek86/smithkit/blob/v0.2.0/docs/migration-0.2.md)
+for the changed imports.
+
 ## Features
 
 - Labeled resistance, reactance, conductance, and susceptance grids.
 - Configurable constant-Q and constant-VSWR circles.
 - Zoom, pan, view reset, and cursor readings.
-- Named traces with colors, visibility, and draggable markers that snap to samples.
+- Named traces with colors, visibility, and keyboard/touch/mouse markers that snap to samples.
 - Marker comparisons: frequency, complex impedance, and wrapped phase differences.
 - Physical impedance/admittance conversions and DOM-independent RF readings.
 - Twelve parameter scales mounted independently of chart zoom.
 - Four peripheral rulers for phase and electrical length.
 - One-port Touchstone 1.x import with RI, MA, and DB representations.
+- Standalone SVG export of the current chart and radial scales.
 - ESM modules and TypeScript declarations.
 
 ## Installation
 
-After publication, install the first release, **0.1.0**, with:
-
-```sh
-npm install smithkit@0.1.0
-```
-
-Until publication, build and install an archive from source:
+Install from npm:
 
 ```sh
-git clone https://github.com/rosek86/smithkit.git
-cd smithkit
-npm ci
-npm pack
+npm install smithkit
 ```
 
-Install the resulting archive in your application:
-
-```sh
-npm install /path/to/smithkit/smithkit-0.1.0.tgz
-```
-
-Building requires Node.js 24 or later. Browser applications need SVG, ES2022,
-and an ESM-compatible build tool. No library stylesheet is required.
+Browser applications need SVG, ES2022, and an ESM-compatible build tool.
+No library stylesheet is required. To build the library from source, see
+[Contributing](https://github.com/rosek86/smithkit/blob/main/CONTRIBUTING.md).
 
 For a complete application using the installed package, see the
 [standalone integration example](https://github.com/rosek86/smithkit/tree/main/examples/basic).
@@ -77,11 +68,11 @@ must be finite and non-negative; both coordinates must be finite. A trace must
 contain at least one sample.
 
 Each new trace receives one marker on its first sample. Drag markers to select
-samples, scroll to zoom, and drag the chart to pan. Markers stay above all sample
-points. `chart.resetView()` restores the initial view, including peripheral rulers.
+samples with a mouse or touch, scroll to zoom, and drag the chart to pan. Markers
+and their focus indicators stay above grid labels and sample points. `chart.resetView()` restores the initial view, including peripheral rulers.
 
 Construct `Smith` only in a browser, such as your framework's mount hook. Importing
-the package and using its calculation or parsing functions does not require a DOM.
+the package and using its calculation or parsing methods does not require a DOM.
 
 Zoom is enabled by default. For a fixed view, call `chart.setZoomEnabled(false)` before or after mounting.
 It disables wheel/double-click zoom and mouse/touch panning and pinch zoom while
@@ -103,6 +94,25 @@ chart.draw('#smith');
 container throws. Call `chart.destroy()` on unmount; it removes the SVG, releases
 event handlers, and cancels queued notifications. Repeated destruction is safe.
 
+### Keyboard and touch markers
+
+Use Tab/Shift+Tab to focus a marker. Arrow keys move through samples in input order;
+Right/Up advances and Left/Down goes back. Shift+Arrow or Page Up/Down moves ten
+samples, and Home/End selects the first/last sample. Navigation clamps at the ends
+and also works when chart zoom is disabled. A single-sample trace remains focusable
+for reading, with its slider marked disabled.
+
+A focused marker has a contrasting outline and exposes its trace name, marker
+number, sample position, and frequency to assistive technology. Hidden traces are
+excluded from keyboard focus. `chart.focusMarker(id)` allows a separate marker
+selector to focus the matching chart control. The demo provides a **Focus on chart**
+button beside its marker selector.
+
+Markers have a 44 CSS px circular hit area and an 18 CSS px triangle, kept constant
+through zoom and container resizing. A marker touch gesture does not pan the chart;
+cancelling it releases the drag state. Touch target areas may overlap for nearby
+markers; use keyboard focus or the demo selector to reach an obscured marker.
+
 ## Traces and markers
 
 Trace and marker IDs are opaque strings, unique within a chart and never reused
@@ -135,6 +145,7 @@ chart.removeMarker(markerB);
 | `clearTraces()`                       | Removes all traces and their markers.                                                                                    |
 | `addMarker(traceId, sampleIndex = 0)` | Returns a marker ID, or `undefined` if the trace is missing.                                                             |
 | `getMarker(id)`                       | Returns a `MarkerSnapshot`, or `undefined` if missing.                                                                   |
+| `focusMarker(id)`                     | Moves keyboard focus to a mounted, visible marker; returns `false` if missing or not focusable.                          |
 | `setMarkerSample(id, sampleIndex)`    | Selects an existing sample and queues a marker notification.                                                             |
 | `removeMarker(id)`                    | Removes one marker without renumbering the remaining markers.                                                            |
 | `compareMarkers(a, b)`                | Returns B − A, or `undefined` if either marker is missing.                                                               |
@@ -206,7 +217,7 @@ const unsubscribe = chart.onEvent((event) => {
     console.log(event.data?.impedanceOhms?.toVector());
     return;
   }
-  // Marker, MarkerDragStart, and MarkerDragEnd always carry a MarkerSnapshot.
+  // Marker, MarkerSelect, MarkerDragStart, and MarkerDragEnd carry a MarkerSnapshot.
   console.log(event.data.markerId, event.data.frequencyHz);
 });
 
@@ -216,7 +227,12 @@ chart.destroy();
 ```
 
 The event types are `Cursor` (`'cursor'`), `Marker` (`'marker'`),
+`MarkerSelect` (`'marker-select'`),
 `MarkerDragStart` (`'marker-drag-start'`), and `MarkerDragEnd` (`'marker-drag-end'`).
+`MarkerSelect` fires synchronously when a marker receives focus or is engaged by
+keyboard navigation or a pointer press. Use it to select the corresponding
+readout; it does not indicate a position change. Keyboard changes use the normal
+queued `Marker` event and do not emit drag lifecycle events.
 Cursor movement is suspended during marker dragging. Drag start/end events fire
 synchronously; marker position notifications are queued and report the latest
 snapshot at delivery. Before delivery, repeated updates to the same marker coalesce
@@ -227,7 +243,7 @@ Trace metadata changes do not emit marker events; refresh metadata after mutatio
 Destruction suppresses application callbacks.
 
 `chart.cursorReading` returns the last cursor position. Cursor and marker readings
-share `SmithReading`; `readReflection(gamma, referenceImpedanceOhms = 50)` produces
+share `SmithReading`; `RfCalculations.readReflection(gamma, referenceImpedanceOhms = 50)` produces
 the same reading without constructing a chart.
 
 | Fields                                                                               | Units / meaning                                                        |
@@ -253,7 +269,7 @@ infinite scalar limit is preserved: perfect match gives infinite return loss;
 For active loads (\|Γ\| > 1), VSWR, standing-wave quantities, reflection loss,
 attenuation, and power transmission are `undefined`. Other quantities remain
 available. Non-finite complex inputs or invalid reference impedances throw
-`RangeError` in the public RF functions. Unrepresentable complex conversion
+`RangeError` in the public RF methods. Unrepresentable complex conversion
 results are `undefined`.
 
 ## Selecting a marker by frequency
@@ -273,22 +289,22 @@ measurement frequency; dragging and sample selection keep that field synchronize
 ## Calculations without a chart
 
 ```ts
-import { Complex, readReflection, impedanceToReflection } from 'smithkit';
+import { Complex, RfCalculations } from 'smithkit';
 
-const gamma = impedanceToReflection(Complex.from(75, 25), 50)!;
-const reading = readReflection(gamma, 50);
+const gamma = RfCalculations.impedanceToReflection(Complex.from(75, 25), 50)!;
+const reading = RfCalculations.readReflection(gamma, 50);
 console.log(reading.impedanceOhms?.toVector()); // Approximately [75, 25].
 console.log(reading.admittanceSiemens?.toVector());
 ```
 
-| Function                                                                 | Input and output                                                                                                |
-| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `reflectionToImpedance(gamma, referenceImpedanceOhms = 50)`              | Γ → physical Z in Ω.                                                                                            |
-| `impedanceToReflection(impedanceOhms, referenceImpedanceOhms = 50)`      | Physical Z in Ω → Γ.                                                                                            |
-| `reflectionToAdmittance(gamma, referenceImpedanceOhms = 50)`             | Γ → physical Y in S.                                                                                            |
-| `admittanceToReflection(admittanceSiemens, referenceImpedanceOhms = 50)` | Physical Y in S → Γ.                                                                                            |
-| `readReflection(gamma, referenceImpedanceOhms = 50)`                     | Complete `SmithReading`.                                                                                        |
-| `compareMarkerReadings(a, b)`                                            | Compare readings without a chart. Each input needs `frequencyHz`, `reflectionCoefficient`, and `impedanceOhms`. |
+| Static method                                                                           | Input and output                                                                                                |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `RfCalculations.reflectionToImpedance(gamma, referenceImpedanceOhms = 50)`              | Γ → physical Z in Ω.                                                                                            |
+| `RfCalculations.impedanceToReflection(impedanceOhms, referenceImpedanceOhms = 50)`      | Physical Z in Ω → Γ.                                                                                            |
+| `RfCalculations.reflectionToAdmittance(gamma, referenceImpedanceOhms = 50)`             | Γ → physical Y in S.                                                                                            |
+| `RfCalculations.admittanceToReflection(admittanceSiemens, referenceImpedanceOhms = 50)` | Physical Y in S → Γ.                                                                                            |
+| `RfCalculations.readReflection(gamma, referenceImpedanceOhms = 50)`                     | Complete `SmithReading`.                                                                                        |
+| `MarkerMeasurements.compare(a, b)`                                                      | Compare readings without a chart. Each input needs `frequencyHz`, `reflectionCoefficient`, and `impedanceOhms`. |
 
 Comparison results contain `frequencyDeltaHz`, `impedanceDeltaOhms`, and
 `phaseDeltaDegrees`. Phase differences use B − A wrapped to **[−180°, 180°)**:
@@ -299,27 +315,27 @@ a point comparison, not sweep phase unwrapping or group delay.
 
 `Complex.from(re, im)` constructs complex numbers. Read components through `re` and `im`. Arithmetic (`add`, `sub`,
 `mul`, `div`, `pow`) returns new values. The class also provides `abs`, `arg`
-(radians), and static functions such as `Complex.conj`, `Complex.sqrt`,
+(radians), and static methods such as `Complex.conj`, `Complex.sqrt`,
 `Complex.exp`, `Complex.log`, and trigonometric/hyperbolic functions and inverses. `toVector()` returns `[real, imaginary]`; `toString(dp)` formats
 a Cartesian value. See the exported declarations for all operations.
 
-Formatting helpers are independent exports: `formatNumber(value)` (three significant
-digits and SI prefixes), `formatComplex(value, unit?, decimalPlaces?)`, and
-`formatComplexPolar(value, unit?, decimalPlaces?)` (phase in degrees). They work
+The `SmithFormatter` class provides static methods: `SmithFormatter.number(value)` (three significant
+digits and SI prefixes), `SmithFormatter.complex(value, unit?, decimalPlaces?)`, and
+`SmithFormatter.polar(value, unit?, decimalPlaces?)` (phase in degrees). They work
 without a chart or DOM. Complex formatters default to three fractional digits.
-`formatNumber` includes spacing so you can append a unit, e.g. `formatNumber(1e9) + 'Hz'`.
+`SmithFormatter.number` includes spacing so you can append a unit, e.g. `SmithFormatter.number(1e9) + 'Hz'`.
 
-`reactanceToComponent(reactanceOhms, frequencyHz)` calculates an ideal equivalent
+`RfCalculations.reactanceToComponent(reactanceOhms, frequencyHz)` calculates an ideal equivalent
 series component without formatting or constructing a chart:
 
 ```ts
-import { reactanceToComponent, formatNumber } from 'smithkit';
+import { RfCalculations, SmithFormatter } from 'smithkit';
 
-const component = reactanceToComponent(-50, 1e9);
+const component = RfCalculations.reactanceToComponent(-50, 1e9);
 if (component?.kind === 'capacitor') {
-  console.log(formatNumber(component.capacitanceFarads) + 'F'); // 3.18 pF
+  console.log(SmithFormatter.number(component.capacitanceFarads) + 'F'); // 3.18 pF
 } else if (component?.kind === 'inductor') {
-  console.log(formatNumber(component.inductanceHenries) + 'H');
+  console.log(SmithFormatter.number(component.inductanceHenries) + 'H');
 }
 ```
 
@@ -347,9 +363,10 @@ chart.layers.vswr.setVisible(true);
 The four grid layers support `setVisible`, `setMinorVisible`, and
 `setStyle(Partial<GridStyle>)`. Style fields: `stroke`, `majorWidth`, `minorWidth`,
 `textColor`, `textFontFamily`, `textFontSize`. Widths are positive finite numbers
-in CSS pixels. Font size is a positive finite number in chart units because labels
-scale with the grid geometry. Partial updates retain other settings. Invalid numeric
-styles throw before any property is changed.
+in CSS pixels. Font size is a positive finite base size in chart units; adaptive
+layout raises it when needed to keep the font size at least 9 CSS pixels in the
+default view. Partial updates retain other settings. Invalid numeric styles throw
+before any property is changed.
 
 `layers.q` and `layers.vswr` support `setVisible`,
 `setStyle({ stroke?, strokeWidth? })`, `addValue`, and `removeValue`.
@@ -359,8 +376,23 @@ Duplicate additions and removal of absent values have no effect.
 
 Grid labels use normalized values; readings use physical units. Strokes default
 to slate gray with 1 px major and 0.6 px minor lines. Stroke widths stay constant
-under zoom; label sizes use SVG user units. Layer controls do not expose drawing
-objects or SVG nodes.
+under zoom. Layer controls do not expose drawing objects or SVG nodes.
+
+Grid labels adapt automatically to the chart's rendered size,
+including static charts with zoom disabled. The layout prioritizes key values,
+hides labels that overlap or extend beyond the default view, and prioritizes zero
+and the highest labeled axis value. It recalculates on resize and layer visibility
+or style changes. Zoom and pan preserve the chosen labels and scale them smoothly
+with the grid. This changes only labels; grid lines and ticks remain unchanged.
+SVG exports preserve the current label layout.
+
+For small static charts, hide minor grid lines and, when unnecessary, peripheral
+scales using the controls above. Very small charts necessarily show fewer values;
+use a larger container for detailed readings. Peripheral labels retain their full
+wording and scale with the chart. Their rulers form two outlined bands: phase
+(transmission/reflection) and electrical length (toward load/generator), with a
+shared tick circle inside each band.
+The independent `SmithScales` panel uses its own responsive layout.
 
 ## Parameter scales
 
@@ -418,12 +450,12 @@ result rejects the operation without changing Z₀ or data. Active marker drags
 cursor indicators are cleared, and marker readings are queued with the new values.
 Changing to the current Z₀ has no effect. Mutations after destruction throw.
 
-Two DOM-independent helpers are also exported:
+Two DOM-independent methods are available on `RfCalculations`:
 
-- `renormalizeReflection(gamma, fromOhms, toOhms)` returns the new complex Γ or
+- `RfCalculations.renormalizeReflection(gamma, fromOhms, toOhms)` returns the new complex Γ or
   `undefined` for a singular/unrepresentable result. Exact open and short limits
   remain Γ = +1 and −1. References must be positive, finite, real ohm values.
-- `renormalizeSamples(samples, fromOhms, toOhms)` returns a new sample array in
+- `RfCalculations.renormalizeSamples(samples, fromOhms, toOhms)` returns a new sample array in
   the same order, preserving frequencies. Invalid samples or a singular result
   throw `RangeError`; the input is never modified.
 
@@ -438,15 +470,15 @@ multiport renormalization are outside the supported scope.
 
 ## Touchstone import
 
-`parseTouchstone(text)` returns `{ samples, referenceImpedanceOhms }`. It accepts
+`Touchstone.parse(text)` returns `{ samples, referenceImpedanceOhms }`. It accepts
 one-port Touchstone 1.x, converts RI/MA/DB into Cartesian Γ and all frequencies
 into Hz, and throws for unsupported or invalid input.
 
 ```ts
-import { Smith, parseTouchstone } from 'smithkit';
+import { Smith, Touchstone } from 'smithkit';
 
 async function showMeasurement(file: File): Promise<Smith> {
-  const { samples, referenceImpedanceOhms } = parseTouchstone(await file.text());
+  const { samples, referenceImpedanceOhms } = Touchstone.parse(await file.text());
   const chart = new Smith(referenceImpedanceOhms);
   chart.draw('#smith');
   chart.addTrace(samples, { name: file.name });
@@ -455,10 +487,43 @@ async function showMeasurement(file: File): Promise<Smith> {
 ```
 
 Omitted options use Touchstone defaults: GHz, S, MA, 50 Ω. For an existing chart,
-use `renormalizeSamples` when the file reference differs from
+use `RfCalculations.renormalizeSamples` when the file reference differs from
 `chart.referenceImpedanceOhms`. The parser itself does not renormalize data.
 Multiport data and Touchstone 2.x are not supported.
 
+## SVG export
+
+`chart.toSvg()` and `scales.toSvg()` return SVG strings. Call them after `draw()`
+while the component is mounted and has a non-zero rendered size; exporting before
+mounting, from a `display: none` container, or after destruction throws an error.
+
+```ts
+const svg = chart.toSvg();
+const blob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+const url = URL.createObjectURL(blob);
+const link = document.createElement('a');
+link.href = url;
+link.download = 'smith-chart.svg';
+document.body.appendChild(link);
+link.click();
+link.remove();
+setTimeout(() => URL.revokeObjectURL(url), 1000);
+```
+
+The chart export preserves the current zoom/pan, layer visibility, labels, traces,
+markers, and visible indicators. It captures the rendered points, including dense
+trace point reduction; it is an image export, not a measurement-data export.
+The scale export combines all twelve axes into one SVG using their current layout
+and displayed readings. To export a marker reading, call `scales.update()` with
+that marker's reflection coefficient before `scales.toSvg()`.
+
+Files have explicit pixel dimensions and a transparent background. Presentation
+styles are inlined so the application's stylesheet is not required. Text remains
+editable, and curved captions retain their internal path references. Font files
+and surrounding HTML controls/backgrounds are not embedded. Downloading is the
+consumer's responsibility; the library does not create files or modify live nodes.
+The demo provides separate **Export chart SVG** and **Export scales SVG** buttons.
+
 ## Development and license
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development, testing, release, and demo

package/dist/lib/MarkerMeasurements.d.ts

@@ -0,0 +1,6 @@
+import type { MarkerSnapshot, MarkerComparison } from './measurements.js';
+export declare class MarkerMeasurements {
+    private constructor();
+    /** Compare B against A without a chart or browser. Frequencies must be finite and non-negative. */
+    static compare(a: Pick<MarkerSnapshot, 'frequencyHz' | 'impedanceOhms' | 'reflectionCoefficient'>, b: Pick<MarkerSnapshot, 'frequencyHz' | 'impedanceOhms' | 'reflectionCoefficient'>): MarkerComparison;
+}

package/dist/lib/MarkerMeasurements.js

@@ -0,0 +1,22 @@
+export class MarkerMeasurements {
+    constructor() { }
+    /** Compare B against A without a chart or browser. Frequencies must be finite and non-negative. */
+    static compare(a, b) {
+        if (![a.frequencyHz, b.frequencyHz].every((frequencyHz) => Number.isFinite(frequencyHz) && frequencyHz >= 0)) {
+            throw new RangeError('Marker frequencies must be finite and non-negative.');
+        }
+        const isFinite = (value) => Number.isFinite(value.re) && Number.isFinite(value.im);
+        const hasPhase = (gamma) => isFinite(gamma) && (gamma.re !== 0 || gamma.im !== 0);
+        const phaseDelta = hasPhase(a.reflectionCoefficient) && hasPhase(b.reflectionCoefficient)
+            ? ((b.reflectionCoefficient.arg() - a.reflectionCoefficient.arg()) * 180) / Math.PI
+            : undefined;
+        const impedanceDelta = a.impedanceOhms && b.impedanceOhms && isFinite(a.impedanceOhms) && isFinite(b.impedanceOhms)
+            ? b.impedanceOhms.sub(a.impedanceOhms)
+            : undefined;
+        return {
+            frequencyDeltaHz: b.frequencyHz - a.frequencyHz,
+            impedanceDeltaOhms: impedanceDelta && isFinite(impedanceDelta) ? impedanceDelta : undefined,
+            phaseDeltaDegrees: phaseDelta === undefined ? undefined : ((phaseDelta + 540) % 360) - 180,
+        };
+    }
+}

package/dist/lib/Smith.d.ts

@@ -1,10 +1,11 @@
 import { TraceSamples } from './samples.js';
 import type { ChartLayers, PeripheralScales } from './layers.js';
-import type { SmithReading } from './rf.js';
+import type { SmithReading } from './rf/RfCalculations.js';
 import type { TraceOptions, TraceUpdateOptions, TraceInfo, MarkerSnapshot, MarkerComparison } from './measurements.js';
 export declare enum SmithEventType {
     Cursor = "cursor",
     Marker = "marker",
+    MarkerSelect = "marker-select",
     MarkerDragStart = "marker-drag-start",
     MarkerDragEnd = "marker-drag-end"
 }
@@ -12,19 +13,21 @@ export type SmithEvent = {
     type: SmithEventType.Cursor;
     data: SmithReading | undefined;
 } | {
-    type: SmithEventType.Marker | SmithEventType.MarkerDragStart | SmithEventType.MarkerDragEnd;
+    type: SmithEventType.Marker | SmithEventType.MarkerSelect | SmithEventType.MarkerDragStart | SmithEventType.MarkerDragEnd;
     data: MarkerSnapshot;
 };
 export declare class Smith {
     private referenceOhms;
     private calcs;
     private scalers;
+    private readonly defaultTransform;
     private transform;
     private zoomEnabled;
     private applyingView;
     private zoomBehavior;
     private svg;
     private resizeObserver;
+    private readonly labelLayout;
     private container;
     private dataContainer;
     private markerContainer;
@@ -52,6 +55,8 @@ export declare class Smith {
     readonly peripheralScales: PeripheralScales;
     constructor(referenceOhms?: number);
     draw(target: string | HTMLElement): void;
+    /** Export the current mounted view as standalone SVG with a transparent background. */
+    toSvg(): string;
     /** Remove this chart and release its event handlers. Safe to call more than once. */
     destroy(): void;
     private updateViewportScale;
@@ -85,6 +90,8 @@ export declare class Smith {
     /** Place a marker on an existing sample; no interpolation is performed. */
     addMarker(traceId: string, sampleIndex?: number): string | undefined;
     removeMarker(id: string): boolean;
+    /** Focus a mounted, visible marker for keyboard interaction. */
+    focusMarker(id: string): boolean;
     setMarkerSample(id: string, sampleIndex: number): boolean;
     /** Select the nearest measured frequency; ties choose the earliest input sample. */
     setMarkerFrequency(id: string, frequencyHz: number): boolean;