svelte-plots-basic 3.2.1 → 3.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2026 Sergey Kucheryavskiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,7 +15,31 @@ These websites and web-applications use `svelte-plots-basic` library:
 
 ## News
 
-### 3.2.0
+### 3.4.0
+
+* Added the `plotActions` property to `Axes` for adding custom buttons to the download panel.
+* Added advanced validation for axis limits, text-label positions, heatmap breaks, and custom plot actions.
+* Fixed text-label positioning and rotation when individual positions are provided.
+* Fixed heatmaps with automatic, custom, or constant-value breaks.
+* Added support for rectangular and constant-height 3D meshes.
+* Improved PNG, SVG, and clipboard export by serializing a clone instead of modifying the visible plot.
+* Fixed the advanced PNG export dialog so a default resolution is always selected, falling back to 300 dpi when necessary.
+* Prevented plot controls from submitting an enclosing HTML form.
+* Added package validation before publishing and synchronized Svelte 5 peer-dependency metadata.
+* Fixed conditionally rendered axes, boxes, and legends so their parent state is cleared when they are removed.
+* Improved heatmap interval processing and added automatically generated colormaps with more than 16 colors.
+* Fixed `TextLegend` positioning at zero and strengthened finite-range validation for 3D axes.
+* Reduced reactive and repeated allocation overhead for axis configuration, text measurement, PNG export, and colormap generation.
+* Added dependency-free regression tests and made them run automatically before packaging.
+* Documented the trust requirements for labels rendered as SVG/HTML markup.
+
+### 3.3.0
+
+* Added advanced "save as PNG" option where user can select size and resolution of the image as well as change the filename.
+* several small improvements and bug fixes.
+
+
+### 3.2.1
 
 * Added mouse click handler option for `Heatmap.svelte` component (returns row and column index of the element).
 
@@ -51,6 +75,13 @@ In addition to Svelte 5 syntax and functionality, this release also introduces a
 
 * **Properites** — from 3.x.x the naming of the properties is more consistent. For example, before the library used properties `borderColor` and `borderWidth` for areas, rectangels, bars and markers, while for lines, segments and multilines the similar properties were named as `lineColor` and `lineWidth`. Now they all have prefix `line*` if it is something about lines or segments and `face*` if it is somthing inside a closed contour. So no more `border*` properties.
 
+
+## Security and label markup
+
+Several title and label properties support SVG/HTML markup and are rendered as raw markup using Svelte's `{@html}` mechanism. This enables formatted labels, HTML entities, subscripts, and superscripts.
+
+Only pass trusted content to these properties. Do not pass unsanitized user input or external data directly as a plot title, axis label, tick label, legend label, or text-label value. Escape untrusted text, or sanitize it with an allow-list appropriate for SVG markup, before passing it to a component.
+
 ## Installation
 
 The set up process is similar to any other Svelte component library. Just use:
@@ -134,6 +165,7 @@ Here is a table with properties of the component related to saving plot to a fil
  `pngRes` | `300` | resolution of PNG image (pixels per inch)
  `clipboardWidth` | `1200` | width of image in clipboard in pixels
  `clipboardHeight` | `800` | height of image in clipboard in pixels
+ `plotActions` | `[]` | array of `{ text, callback }` objects for adding custom buttons to the download panel.
 
 Please pay attention that most of the browsers enable clipboard functionality only if website is available via HTTPS.
 
@@ -835,15 +867,12 @@ Here is an example of simple 3D scatter plot:
 <Axes limX={[-10, 10]} limY={[-10, 10]} limZ={[-10, 10]} {zoom} {phi} {theta}>
 	<Points {xValues} {yValues} {zValues} />
 
-	<XAxis showGrid={true} title="X" />
-	<YAxis showGrid={true} title="Y" />
-	<ZAxis showGrid={true} title="Z" />
+	<XAxis showGrid={true} label="X" />
+	<YAxis showGrid={true} label="Y" />
+	<ZAxis showGrid={true} label="Z" />
 </Axes>
 ```
 
 You can also add `Lines`, `Segments` and `Mesh` series to 3D plots.
 
 Check more advanced example in Svelte REPL with mouse and keyboard support, and more: [plots-3d](https://svelte.dev/playground/2294eecba7d7477ab9a09c1734d32ac2)
-
-
-

package/package.json

@@ -1,10 +1,16 @@
 {
    "name": "svelte-plots-basic",
    "description": "Svelte components for creating simple plots",
-   "version": "3.2.1",
+   "version": "3.4.0",
    "author": "Sergey Kucheryavskiy",
    "license": "MIT",
    "private": false,
+   "type": "module",
+   "scripts": {
+      "check": "node scripts/check.cjs",
+      "test": "node --test",
+      "prepack": "npm run check && npm test"
+   },
    "exports": {
       "./constants":  "./src/constants.js",
       "./utils":  "./src/methods.js",
@@ -16,6 +22,9 @@
    "devDependencies": {
       "svelte": "^5.x.x"
    },
+   "peerDependencies": {
+      "svelte": "^5.0.0"
+   },
    "dependencies": {
       "mdatools": "^1.x.x"
    },

package/src/2d/Area.svelte

@@ -32,7 +32,6 @@
    import { val2p, checkCoords, handleClick, transformCoords } from '../methods';
    import { LINE_STYLES } from '../constants';
 
-   /** @type {Props} */
    let {
 	   xValues,                       // vector or array with x-coordinates of the points
       yValues,                       // vector or array with y-coordinates of the points
@@ -66,4 +65,3 @@
    <polygon points={pa}/>
 </g>
 {/if}
-

package/src/2d/Axes.svelte

@@ -30,13 +30,14 @@
 <script>
    import { setContext } from 'svelte';
    import { Colors, PLOT_FONT_SIZE, AXES_MARGIN_FACTORS, TICK_SIZE, LINE_STYLES, MARKER_SYMBOLS } from '../constants.js';
-   import { downloadSVG, downloadPNG, copyToClipboard, checkArray, getScale, getAxisScale, getXAxisParams, getYAxisParams,
+   import { downloadSVG, downloadPNG, copyToClipboard, getScale, getAxisScale, getXAxisParams, getYAxisParams,
             transformCoords, getColormapLegendParams, getColormapLegendCoords, getTickFactorLabel,
             getGroupLegendCoords, text2svg,
             invTransformCoords } from '../methods.js';
 
    import AxisLines from './AxisLines.svelte';
    import AxisTickLabels from './AxisTickLabels.svelte';
+   import ExportDialog from '../ExportDialog.svelte';
 
 
    let {
@@ -45,6 +46,7 @@
       limY = [0, 1],
       margins = [1.0, 1.1, 0.55, 0.60],
       downloadLinks = 'none',
+      plotActions = [],
       fileName = 'plot',
       pngWidth = 8,
       pngHeight = 8,
@@ -59,6 +61,44 @@
    } = $props();
 
 
+   const actions = $derived.by(() => {
+      if (plotActions == null) return [];
+
+      if (!Array.isArray(plotActions)) {
+         console.error('Axes: "plotActions" must be an array.');
+         return [];
+      }
+
+      return plotActions.filter((action, index) => {
+         const isValid =
+            action &&
+            typeof action.text === 'string' &&
+            typeof action.callback === 'function';
+
+         if (!isValid) {
+            console.error(
+               `Axes: plot action ${index + 1} must contain a text string and callback function.`
+            );
+         }
+
+         return isValid;
+      });
+   });
+
+
+   // Check that axis limits contain a finite, meaningful numeric range.
+   function hasUsableRange(lim) {
+      if (!Array.isArray(lim) || lim.length !== 2) return false;
+      if (!lim.every(v => typeof v === 'number' && Number.isFinite(v))) return false;
+
+      const span = Math.abs(lim[1] - lim[0]);
+      const scale = Math.max(Math.abs(lim[0]), Math.abs(lim[1]));
+
+      return Number.isFinite(1 / span) &&
+         span > Number.EPSILON * scale * 16;
+   }
+
+
    /* handler for mouse  events */
    function handleMouse(e, f) {
       if (f && e.target.id == "axes-box") {
@@ -103,9 +143,14 @@
       downloadPNG(plotElement, fileName, pngWidth, pngHeight, pngRes);
    }
 
+   /* Open advanced PNG export dialog. */
+   let showExportDialog = $state(false);
+   function handleClickPNGAdvanced() { showExportDialog = true; }
+   function handleCloseExportDialog() { showExportDialog = false; }
+
 
    // unique ID for clip path
-   const clipPathID = 'plottingArea' + Math.round(Math.random() * 10000);
+   const clipPathID = 'plottingArea' + Math.random().toString(36).slice(2);
 
    // pointers to plot DOM element and its width and height
    let plotElement = $state(0);
@@ -132,8 +177,8 @@
 
    // plot status
    const isOk = $derived(
-      checkArray(limX, 2) &&
-      checkArray(limY, 2) &&
+      hasUsableRange(limX) &&
+      hasUsableRange(limY) &&
       width > (pxMargins[1] + pxMargins[3]) &&
       height > (pxMargins[0] + pxMargins[2])
    );
@@ -166,14 +211,14 @@
 
    // parameters of plot title
    const plotTitle = $derived(text2svg(title));
-   const titleHeight = $derived(plotTitle ? (plotTitle.length === title.left ? 1.0 : 1.4) : 0);
+   const titleHeight = $derived(plotTitle ? (plotTitle.length === title.length ? 1.0 : 1.4) : 0);
 
    // default parameters of box, axis elements, colomap legend and group legend
-   let box = $state({show: false});
-   let xaxis = $state({show: false, error: ''});
-   let yaxis = $state({show: false, error: ''});
-   let clg = $state({show: false, colmap: null, breaks: null});
-   let glg = $state({show: false, items: null, position: null});
+   let box = $state.raw({show: false});
+   let xaxis = $state.raw({show: false, error: ''});
+   let yaxis = $state.raw({show: false, error: ''});
+   let clg = $state.raw({show: false, colmap: null, breaks: null});
+   let glg = $state.raw({show: false, items: null, position: null});
 
    // set colormap legend parameters if requested
    const clgParams = $derived(isOk && clg && clg.show ? getColormapLegendParams(clg) : null);
@@ -220,7 +265,7 @@
 
       {#if coords.tickCoords.length === 2 && coords.tickLabels.length === coords.tickCoords[1][0].length}
       <AxisTickLabels las={params.las} pos={params.pos} tickCoords={coords.tickCoords}
-         tickLabels={coords.tickLabels} tickColor={Colors.DARKGRAY} hideLast={params.hideLast}/>
+         tickLabels={coords.tickLabels} textColor={Colors.DARKGRAY} />
       {/if}
 
       <!-- tick factor -->
@@ -262,7 +307,7 @@
       <text {x} y={coords.ltop} dx="1.2em" dy="-0.25em" dominant-baseline="hanging"
          fill={params.labelColor}
          font-size="{params.fontSize}em"
-         text-anchor="right"
+         text-anchor="end"
       >{@html getTickFactorLabel(params.labelsFactor)}</text>
    {/if}
 {/snippet}
@@ -340,11 +385,6 @@
             user-select: none;
          }
 
-         .series-points text {
-            /* dominant-baseline: central;
-            alignment-baseline: central */
-         }
-
          .tick-labels text,
          .tick-labels tspan,
          .series-textlabels text,
@@ -444,27 +484,18 @@
 
             <!-- box -->
             <g class="axes-box">
-            {#if box.show}
-            <rect stroke={box.lineColor} stroke-width="{box.lineWidth}px" fill="transparent"
+            <!-- The plot callback requires real pointer coordinates; a keyboard-generated coordinate would be arbitrary. -->
+            <!-- svelte-ignore a11y_click_events_have_key_events -->
+            <rect stroke={box.show ? box.lineColor : 'transparent'}
+               stroke-width={box.show ? box.lineWidth + 'px' : '0'}
+               fill="transparent"
                x={cpx[0]} y={cpy[1]} width={cpx[1] - cpx[0]} height={cpy[0] - cpy[1]}
                id="axes-box"
-               onkeydown={handleClick}
                onclick={handleClick}
                onmousemove={handleMove}
                onmousedown={handleDown}
                onmouseup={handleUp}
             />
-            {:else}
-            <rect stroke="transparent" fill="transparent"
-               x={cpx[0]} y={cpy[1]} width={cpx[1] - cpx[0]} height={cpy[0] - cpy[1]}
-               id="axes-box"
-               onkeydown={handleClick}
-               onclick={handleClick}
-               onmousemove={handleMove}
-               onmousedown={handleDown}
-               onmouseup={handleUp}
-            />
-            {/if}
             </g>
 
 
@@ -501,11 +532,24 @@
    </p>
    {:else}
    <div class="download-links">
-      <button onclick={handleClickSVG} onkeydown={handleClickSVG}>⇩ svg</button>
-      <button onclick={handleClickPNG} onkeydown={handleClickPNG}>⇩ png</button>
-      <button onclick={handleClickCopy} onkeydown={handleClickCopy}>⧉ copy</button>
+      <button type="button" onclick={handleClickSVG}>↓   svg</button>
+      <button type="button" onclick={handleClickPNG}>↓ png</button>
+      <button type="button" onclick={handleClickPNGAdvanced}>↓ png+</button>
+      <button type="button" onclick={handleClickCopy}>⧉ copy</button>
+      {#if actions.length > 0}
+      <span class="divider">⋮</span>
+      {#each actions as ac}
+      <button type="button" onclick={ac.callback}>{ac.text}</button>
+      {/each}
+      {/if}
    </div>
    {/if}
+
+   {#if showExportDialog}
+      <ExportDialog {plotElement} {fileName}
+         initialWidth={pngWidth} initialRes={pngRes}
+         onclose={handleCloseExportDialog} />
+   {/if}
 </div>
 
 <style>
@@ -534,7 +578,6 @@
       transition: bottom 0.35s ease;
       box-shadow: 0 0 0.75em #00000060;
       margin: 0.6em;
-      box-sizing: border-box;
 
       display: flex;
       align-items: center;
@@ -549,6 +592,9 @@
       background: #fafafa;
       border-radius: 0.35em;
       padding: 0.25em 0.5em;
+      margin: 0 1px;
+
+      line-height: 1.25;
    }
 
    .download-links > button:hover{
@@ -564,6 +610,12 @@
       background: #4488ee;
    }
 
+   .download-links > .divider {
+      display: inline-block;
+      width: 1em;
+      text-align: center;
+      color: #909090;
+   }
 
    /* Plot container */
    .plot-container {
@@ -621,4 +673,4 @@
       min-width: 100%;
    }
 
-</style>
+</style>

package/src/2d/Bars.svelte

@@ -34,7 +34,6 @@
    import Rectangles from './Rectangles.svelte';
 
 
-   /** @type {Props} */
    let {
 	   xValues,                       // vector with x-coordinates of middle points of the bars.
       yValues,                       // vector with y-coordinates of top points of the bars.
@@ -68,11 +67,10 @@
          console.error('Bars: if only one bar must be shown, value for property "barWidthExact" should be provided.');
          return null;
       } else {
-         w = 0;
-         let lw = 0;
+         w = Infinity;
          for (let i = 1; i < n; i++) {
-            lw = Math.abs(xv.v[i - 1] - xv.v[i]);
-            if (lw > w) w = lw;
+            const lw = Math.abs(xv.v[i - 1] - xv.v[i]);
+            if (lw < w) w = lw;
          }
       }
 
@@ -117,4 +115,4 @@
 {#if isOk}
 <Rectangles className="series series-bar" left={x.left} width={x.width} top={y.top} height={y.height}
    lineWidth={lineWidth} {lineColor} {faceColor} {onclick} />
-{/if}
+{/if}

package/src/2d/Box.svelte

@@ -16,7 +16,7 @@
    ```
 -->
 <script>
-   import { getContext } from 'svelte';
+   import { getContext, onDestroy } from 'svelte';
 
    let {lineWidth = 1, lineColor = '#606060'} = $props();
    const axes = getContext('axes');
@@ -24,5 +24,8 @@
    $effect(() => {
       axes.setBox({show:true, lineWidth, lineColor});
    });
-</script>
 
+   onDestroy(() => {
+      axes.setBox({show: false});
+   });
+</script>

package/src/2d/ColormapLegend.svelte

@@ -34,7 +34,7 @@
    ```
 -->
 <script>
-   import { getContext } from 'svelte';
+   import { getContext, onDestroy } from 'svelte';
    import { Colors } from '../constants';
 
 
@@ -52,7 +52,10 @@
    $effect(() => {
       axes.setColmapLegend({show, breaks, colmap, labels, labelColor, fontSize})
    });
-</script>
 
+   onDestroy(() => {
+      axes.setColmapLegend({show: false});
+   });
+</script>
 
 

package/src/2d/Heatmap.svelte

@@ -27,13 +27,12 @@
    import { getContext } from 'svelte';
    import { ismatrix, isvector } from 'mdatools/arrays';
    import { expandgrid } from 'mdatools/misc';
-   import { split } from 'mdatools/stat';
+   import { range, split } from 'mdatools/stat';
 
    import { getcolmap, transformObjects, transformCoords, seq } from '../methods';
    import { HEATMAP_NUM_SPLITS } from '../constants';
 
 
-   /** @type {Props} */
    let {
       values,                        // Matrix with values to show heatmap for
       breaks,                        // vector with breaks to distribute the values in
@@ -42,6 +41,54 @@
    } = $props();
 
 
+   function validateBreaks(values) {
+      if (!values || values.length < 2) {
+         console.error('Heatmap: "breaks" must contain at least two values.');
+         return null;
+      }
+
+      const items = Array.from(values);
+
+      if (items.some(value =>
+         typeof value !== 'number' || Number.isNaN(value)
+      )) {
+         console.error('Heatmap: values in "breaks" must be numeric.');
+         return null;
+      }
+
+      if (items.some((value, index) =>
+         index > 0 && value <= items[index - 1]
+      )) {
+         console.error('Heatmap: values in "breaks" must be strictly increasing.');
+         return null;
+      }
+
+      return values;
+   }
+
+
+   function findInterval(value, breaks) {
+      let low = 1;
+      let high = breaks.length - 1;
+
+      while (low < high) {
+         const middle = Math.floor((low + high) / 2);
+
+         if (value <= breaks[middle]) {
+            high = middle;
+         } else {
+            low = middle + 1;
+         }
+      }
+
+      const index = low - 1;
+
+      return value > breaks[index] && value <= breaks[index + 1]
+         ? index
+         : -1;
+   }
+
+
 
    // check that values are provided as a matrix
    let v = $derived(ismatrix(values) && values.nrows > 0 && values.ncols > 0 ? values : null);
@@ -49,19 +96,37 @@
    // check and process left values for breaks
    let lb = $derived.by(() => {
       if (!v) return null;
-      if (breaks && Array.isArray(breaks)) return breaks;
-      if (breaks && isvector(breaks)) return breaks.v;
-      return split(v.v, HEATMAP_NUM_SPLITS).v;
+
+      if (breaks !== undefined && breaks !== null) {
+         if (Array.isArray(breaks)) return validateBreaks(breaks);
+         if (isvector(breaks)) return validateBreaks(breaks.v);
+
+         console.error('Heatmap: "breaks" must be an array or Vector.');
+         return null;
+      }
+
+      const valueRange = range(v.v);
+      if (valueRange[0] === valueRange[1]) {
+         const value = valueRange[0];
+         const delta = Math.abs(value) > 0 ? Math.abs(value) * 0.01 : 1;
+         const lower = Number.isFinite(value - delta) ? value - delta : value;
+         const upper = Number.isFinite(value + delta) ? value + delta : value;
+         return validateBreaks([lower, upper]);
+      }
+
+      return validateBreaks(split(v.v, HEATMAP_NUM_SPLITS).v);
    });
 
    // check and process colormap values
    let lc = $derived.by(() => {
+      if (!lb) return null;
+
       if (colmap) {
          if (!Array.isArray(colmap)) {
             console.error('Heatmap: parameter "colmap" must be array with colors.');
             return null;
          }
-         if (colmap.length !== breaks.length - 1) {
+         if (colmap.length !== lb.length - 1) {
             console.error('Heatmap: number of color values in colormap does not match number of intervals defined by breaks.');
             return null;
          }
@@ -81,8 +146,11 @@
       const [top, left] = lt;
       const nv = left.length;  // number of values in matrix
       const nb = lb.length;    // number of breaks
-      const rl = Array(nb).fill().map(() => []);     // coordinates of left for every break
-      const rt = Array(nb).fill().map(() => []);     // coordinates of top for every break
+      const intervalCount = nb - 1;
+      const rl = Array.from({length: intervalCount}, () => []);  // coordinates of left for every interval
+      const rt = Array.from({length: intervalCount}, () => []);  // coordinates of top for every interval
+      const rr = Array.from({length: intervalCount}, () => []);  // row indices for every interval
+      const rc = Array.from({length: intervalCount}, () => []);  // column indices for every interval
 
       // adjust left side for the first break and right side for the last
       const llb = lb.slice();
@@ -93,15 +161,15 @@
       // loop over all breaks
       for (let j = 0; j < nv; j++) {
          const vj = v.v[j];
-         for (let i = 0; i < nb - 1; i++) {
-            if (vj > llb[i] && vj <= llb[i + 1]) {
-               rl[i].push(left.v[j] - 0.5);
-               rt[i].push(v.nrows - top.v[j] + 1.5);
-               break;
-            }
-         }
+         const i = findInterval(vj, llb);
+         if (i === -1) continue;
+
+         rl[i].push(left.v[j] - 0.5);
+         rt[i].push(v.nrows - top.v[j] + 1.5);
+         rr[i].push(top.v[j]);
+         rc[i].push(left.v[j]);
       };
-      return {rl, rt};
+      return {rl, rt, rr, rc};
    });
 
 
@@ -119,13 +187,12 @@
       const el = e.target;
       if (el.tagName !== 'rect') return;
 
-      const pel = el.parentNode.parentNode;
-      const pr = pel.getBoundingClientRect();
-      const r = el.getBoundingClientRect();
-      const x = (r.x - pr.x) + r.width * 0.2;
-      const y = (r.y - pr.y) + r.height * 0.2;
-      onclick(Math.abs(Math.round(y / r.height)), Math.abs(Math.round(x / r.width)))
-      e.stopPropagation();
+      const row = parseInt(el.getAttribute('data-row'));
+      const col = parseInt(el.getAttribute('data-col'));
+      if (!isNaN(row) && !isNaN(col)) {
+         onclick(row, col);
+         e.stopPropagation();
+      }
    }
 
 
@@ -143,7 +210,7 @@
       {#if rx[i].length > 0}
          <!-- loop over elements which fall into the interval -->
          {#each rx[i] as v, j}
-            <rect x={rx[i][j]} y={ry[i][j]} width={rw} height={rh}/>
+            <rect x={rx[i][j]} y={ry[i][j]} width={rw} height={rh} data-row={wc.rr[i][j]} data-col={wc.rc[i][j]}/>
          {/each}
       {/if}
       </g>