smithkit 0.2.0 → 0.3.0

package/README.md

@@ -5,6 +5,10 @@ interactive SVG Smith charts, RF calculations, and S11 measurement exploration.
 
 [Try the interactive demo](https://rosek86.github.io/smithkit/).
 
+Upgrading from 0.2.x? Version 0.3.0 replaces `GridLayer.setMinorVisible()` with
+`setDetail('basic' | 'standard' | 'detailed')`. Replace `false` with `'standard'`
+and `true` with `'detailed'`; `'basic'` shows only the principal circles.
+
 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.
@@ -20,7 +24,7 @@ for the changed imports.
 - 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.
+- Standalone SVG and configurable PNG export of the chart and radial scales.
 - ESM modules and TypeScript declarations.
 
 ## Installation
@@ -344,6 +348,69 @@ Zero frequency, zero reactance, and unrepresentable results return `undefined`.
 Non-finite reactance or negative/non-finite frequency throws `RangeError`.
 This is a single-frequency equivalence, not a fitted circuit model.
 
+## Appearance and themes
+
+`Smith` and `SmithScales` accept the same appearance configuration. The default
+is the light preset with a transparent background. The dark preset includes a
+solid dark background so its labels remain readable when embedded or exported.
+
+```ts
+import { Smith, SmithScales } from 'smithkit';
+import type { SmithAppearance } from 'smithkit';
+
+const appearance: SmithAppearance = {
+  theme: 'dark',
+  overrides: {
+    fontFamily: 'Arial, sans-serif',
+    grid: { majorWidth: 1.2 },
+    cursor: { impedanceColor: '#fbbf24' },
+    marker: { focusColor: '#38bdf8' },
+    traceColors: ['#38bdf8', '#fb923c', '#a78bfa'],
+  },
+};
+const chart = new Smith(50, appearance);
+const scales = new SmithScales(appearance);
+chart.draw('#smith');
+scales.draw('#scales');
+
+// Update both independent components using the same configuration.
+chart.setAppearance({ theme: 'light' });
+scales.setAppearance({ theme: 'light' });
+```
+
+Each `setAppearance` call replaces the previous preset and overrides; omitted
+settings return to the selected preset, or light when `theme` is omitted.
+Nested overrides are partial. Appearance is scoped to each component and does not
+change the surrounding application's CSS or other chart instances.
+
+| Override                   | Settings                                                                                                                                                                             |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `background`, `fontFamily` | Component background and shared font family.                                                                                                                                         |
+| `grid`                     | `stroke`, `textColor`, `majorWidth`, `minorWidth`, `fontSize`.                                                                                                                       |
+| `boundary`                 | `stroke`, `width` for the Smith chart boundary.                                                                                                                                      |
+| `circles`                  | `q`, `vswr` colors and shared `width`.                                                                                                                                               |
+| `scales`                   | `stroke`, `boundaryColor`, `textColor`, `valueColor`, `indicatorColor`, `indicatorOutline`; `fontSize` for radial ticks, `titleFontSize`, `valueFontSize`, and `peripheralFontSize`. |
+| `cursor`                   | `pointColor`, `impedanceColor`, `admittanceColor`, `pointSize` (dot diameter), `lineWidth`.                                                                                          |
+| `marker`                   | `outlineColor`, `textColor`, `focusColor`, `focusHaloColor`. Marker fill follows its trace color.                                                                                    |
+| `traceColors`              | Non-empty palette for automatically colored traces.                                                                                                                                  |
+
+Colors must be solid CSS colors accepted by the library's color parser, including
+hex, RGB, HSL, named colors, and `transparent`; CSS variable references are not
+accepted in the configuration. Numeric values must be positive and finite.
+Line widths and cursor point size are CSS pixels. Font sizes are SVG chart/scale
+units and follow the existing layout; grid labels retain their adaptive minimum
+size. Marker geometry and the 44 px touch target stay unchanged.
+
+Appearance updates retain zoom, samples, marker selection/focus, layer visibility,
+and scale readings. They recolor existing and future automatically colored traces.
+Explicit colors passed through trace options and explicit layer styles take
+precedence and survive theme changes. Applying a new appearance does not reset
+those individual overrides. Invalid appearance settings throw before making changes.
+
+SVG exports resolve the appearance without requiring theme CSS. A configured
+background is included in the exported image; `transparent` preserves transparency.
+The **Theme** selector in the demo's **Chart settings** dialog updates both library components and the demo UI.
+
 ## Grid layers
 
 Resistance and reactance are initially visible. Conductance, susceptance, Q,
@@ -354,13 +421,15 @@ chart.layers.resistance.setVisible(false);
 chart.layers.reactance.setVisible(false);
 chart.layers.conductance.setVisible(true);
 chart.layers.susceptance.setVisible(true);
-chart.layers.conductance.setMinorVisible(false);
+chart.layers.conductance.setDetail('standard');
+chart.layers.conductance.setLabelsVisible(false);
+chart.layers.susceptance.setLabelsVisible(false);
 chart.layers.susceptance.setStyle({ stroke: '#64748b', textColor: '#2a7f62' });
 chart.layers.vswr.addValue(4);
 chart.layers.vswr.setVisible(true);
 ```
 
-The four grid layers support `setVisible`, `setMinorVisible`, and
+The four grid layers support `setVisible`, `setLabelsVisible`, `setDetail`, 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 base size in chart units; adaptive
@@ -368,6 +437,23 @@ 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.
 
+Choose `setDetail('basic' | 'standard' | 'detailed')` independently for each grid layer:
+
+- **Basic:** complete circles and arcs for normalized values 0.2, 0.5, 1, 2, and 5,
+  with matching axis/rim labels and the zero label. Intended for small or static charts.
+- **Standard:** the full major grid and its labels, without minor lines.
+- **Detailed** (default): the full major and minor grid.
+
+Changing detail preserves layer visibility, styles, and the current view. Label
+collision handling still applies at every level. Peripheral scales and Q/VSWR
+circles are independent. The demo's **Chart settings → Grid detail** selector updates all four grid layers.
+
+Use `setLabelsVisible(false)` to hide a grid layer's labels while keeping its lines.
+Labels default to visible. The setting persists through detail, style, theme, and
+whole-layer visibility changes and is included in SVG exports. Calling
+`setLabelsVisible(true)` restores labels allowed by the current detail and collision
+layout; it does not show a hidden layer. The **Grid labels** checkbox in the demo’s **Chart settings** dialog controls all four grid layers together. Peripheral scale labels are unaffected.
+
 `layers.q` and `layers.vswr` support `setVisible`,
 `setStyle({ stroke?, strokeWidth? })`, `addValue`, and `removeValue`.
 Circle stroke widths are positive finite numbers in CSS pixels.
@@ -491,9 +577,92 @@ 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.
 
+## PNG and report export
+
+`chart.toPng(options?)` and `scales.toPng(options?)` return `Promise<Blob>` with MIME
+type `image/png`. Call them in a browser after mounting the components at non-zero
+sizes, as with SVG export. The current view, labels, colors, markers, and scale
+readings are captured without modifying the live components.
+
+```ts
+import { SmithScales } from 'smithkit';
+
+const scales = new SmithScales();
+scales.draw('#scales');
+const png = await chart.toPng({ width: 3200, background: 'white', legend: true });
+// Use the Blob with your application's download, preview, or upload flow.
+const report = await chart.toPng({ width: 2400, scales, legend: true });
+const scalePng = await scales.toPng({ width: 1200, background: 'transparent' });
+```
+
+- `width` / `height`: output pixels. Omit both to use the snapshot's natural size;
+  specify one to preserve proportions. With both set, the complete image is
+  centered and fitted without distortion or cropping. Padding uses the chosen
+  background, or transparency when no background is specified.
+- `background`: omit to keep component backgrounds, or pass a concrete CSS color
+  (for example `'#fff'`) or `'transparent'` to replace them. Chart colors stay as
+  configured; choose a suitable chart theme for your report background.
+- `legend` (chart only): append the names and colors of visible traces. Long names
+  wrap; hidden traces are omitted. Default: `false`.
+- `markerLegend` (chart only): independently append marker descriptions below the chart/scales.
+  Default: `false`. `true` includes every marker of visible traces, with trace name,
+  marker number, frequency, and impedance. Use an options object to select `markerIds`
+  and `fields` (`frequency`, `impedance`, `admittance`, `reflectionCoefficient`, `vswr`,
+  `returnLoss`). Fields use Hz with SI prefixes, Ω, mS, dimensionless Γ, VSWR ratios,
+  and dB respectively. Empty `markerIds` selects none; empty `fields` keeps only names
+  and marker numbers. Hidden traces are always omitted, duplicate selections appear
+  once, and unknown IDs/fields throw. Long descriptions wrap. Readings are captured at
+  export invocation, without moving markers or changing the live view.
+- `scales` (chart only): a mounted `SmithScales` instance to place centered below the chart.
+  Its current responsive layout and readings are preserved. Use `scaleReadout` to
+  export a specific reading independently of the live view.
+
+```ts
+// Works with toSvg() as well. Trace and marker legends are independent.
+const png = await chart.toPng({
+  legend: false,
+  markerLegend: {
+    fields: ['frequency', 'impedance', 'vswr'],
+    // Omit markerIds to include all markers of visible traces.
+  },
+});
+```
+
+Dimensions must be positive integers, at most 8192 px per side and 32 megapixels
+in total. Invalid options and unavailable/destroyed components reject the promise.
+PNG export uses browser SVG decoding and Canvas 2D and releases temporary image URLs.
+Fonts must be available to the browser; external font files are not embedded.
+Export size increases resolution; it does not change the current label density.
+
+The demo's **Export** dialog supports chart, scales, or a combined report,
+custom dimensions/background, and independent trace and marker legends. **Include marker legend** reveals field and marker checkboxes; it is disabled for scales-only exports. The default output width is 3200 px. Choose PNG or SVG in the same dialog; both formats support these report options. The demo starts in dark mode. For exports containing parameter scales, **Scale readings** explicitly selects a marker or **None**, independently of the Cursor/Marker tab. Marker exports include the trace name, marker number, and frequency; cursor readings are not exported.
+
+To export a specific scale reading without changing the live view, pass `readout` to
+`scales.toSvg()` / `scales.toPng()`, or `scaleReadout` to a combined chart export:
+
+```ts
+import { Complex, SmithScales } from 'smithkit';
+
+const scales = new SmithScales();
+scales.draw('#scales');
+const report = await chart.toPng({
+  scales,
+  scaleReadout: {
+    reflectionCoefficient: Complex.from(0.2, 0.3),
+    label: 'Antenna · Marker 1 · Frequency: 1 GHz',
+  },
+});
+```
+
+Use `{ reflectionCoefficient: null }` for scales without readings. Omit the override to
+preserve the current readings. Labels wrap to fit the exported scales.
+
 ## SVG export
 
-`chart.toSvg()` and `scales.toSvg()` return SVG strings. Call them after `draw()`
+`chart.toSvg(options?)` and `scales.toSvg(options?)` return SVG strings synchronously.
+They accept the same `SmithImageExportOptions` / `ImageExportOptions` as PNG export,
+including size, background, legend, and scales. Omitting options preserves the
+original standalone SVG snapshot. 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.
 
@@ -517,12 +686,13 @@ The scale export combines all twelve axes into one SVG using their current layou
 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
+Files have explicit pixel dimensions and preserve the configured component background
+(transparent by default). 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.
+In the demo, choose **Export → Format → SVG**, then select chart, scales, or the combined report.
 
 ## Development and license
 

package/dist/lib/Smith.d.ts

@@ -1,4 +1,6 @@
-import { TraceSamples } from './samples.js';
+import type { SmithImageExportOptions } from './svg/export.js';
+import type { SmithAppearance } from './appearance/types.js';
+import type { TraceSamples } from './samples.js';
 import type { ChartLayers, PeripheralScales } from './layers.js';
 import type { SmithReading } from './rf/RfCalculations.js';
 import type { TraceOptions, TraceUpdateOptions, TraceInfo, MarkerSnapshot, MarkerComparison } from './measurements.js';
@@ -18,63 +20,37 @@ export type SmithEvent = {
 };
 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;
-    private reactanceAxis;
-    private constResistance;
-    private constReactance;
-    private constConductance;
-    private constSusceptance;
-    private constSwrCircles;
-    private constQCircles;
-    private cursor;
-    private peripheralScaleRenderer;
+    private theme;
+    private readonly renderer;
     private data;
     private destroyed;
-    private mouseGesture;
     private nextDatasetColor;
     private nextTraceId;
     private nextMarkerId;
     private traceMetadata;
     private markerIds;
     private draggedMarkers;
-    private cursorBeforeMarkerDrag;
     private listeners;
     readonly layers: ChartLayers;
     readonly peripheralScales: PeripheralScales;
-    constructor(referenceOhms?: number);
+    constructor(referenceOhms?: number, appearance?: SmithAppearance);
+    /** Replace the appearance while retaining explicit layer styles and trace colors. */
+    setAppearance(appearance: SmithAppearance): void;
     draw(target: string | HTMLElement): void;
-    /** Export the current mounted view as standalone SVG with a transparent background. */
-    toSvg(): string;
+    /** Export the current mounted view as standalone SVG with its configured background. */
+    toSvg(options?: SmithImageExportOptions): string;
+    private exportLegend;
+    /** Export the mounted view as PNG, optionally with radial scales and a trace legend. */
+    toPng(options?: SmithImageExportOptions): Promise<Blob>;
     /** Remove this chart and release its event handlers. Safe to call more than once. */
     destroy(): void;
-    private updateViewportScale;
     private assertAlive;
-    private createScalers;
-    private cursorMove;
     private markerDragChanged;
-    private initCursor;
     /** Last cursor position. Use cursor events to detect pointer leave. */
     get cursorReading(): SmithReading;
-    private initializeZoom;
     /** Enable or disable wheel, double-click, and mouse/touch zoom/pan. Keeps the current view. */
     setZoomEnabled(enabled: boolean): void;
-    private applyView;
     resetView(): void;
-    private onZoom;
-    private cursorContainer;
-    private drawReactanceAxis;
     /** Add a named trace with one initial marker. Returns a chart-local, stable ID. */
     addTrace(values: TraceSamples, options?: TraceOptions): string;
     /** Detached metadata snapshots; IDs and marker display numbers survive removals. */