svelte-plots-basic 2.5.7 → 3.0.0

package/src/2d/Multilines.svelte

@@ -1,67 +1,94 @@
-<script>
-   /****************************************************
-   * Multilines                                        *
-   * --------------------                              *
-   * shows series of lines components                  *
-   *****************************************************/
-
-   import { getContext } from 'svelte';
-   import { ismatrix } from 'mdatools/arrays';
-   import { Colors } from '../Colors';
-   import { val2p } from '../Utils';
+<!--
+@component Adds a series of polylines (like `<Lines>` but with several of those).
 
+   Main properties:
+   - `xValues` - array of vector with x-coordinates of the points.
+   - `yValues` - Matrix (object of class `Matrix` from `mdatools/array`) with y-coordinates of the points.
+   - `lineColor` - lines color, default: `Colors.PRIMARY`.
+   - `lineWidth` - width (thickness) of the lines in pixels, defailt: `1`.
+   - `lineType` -  type of segment lines (`1` - solid, `2` - dashed, `3` - dotted, `4` - dashdot).
+   - `onclick` - function (callback) to be called when user clicks on a polyline.
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   Example:
 
-	export let xValues;                       // vector or array with x-coordinates of the points
-   export let yValues;                       // matrix (!) with y-coordinates of the points - every column is separate line
-   export let lineWidth = 1;                 // width (thickness) of the lines
-   export let lineColor = Colors.PRIMARY;    // color of the lines
-   export let lineType = 1;                  // type of the lines (1 - solid, 2 - dashed, 3 - dotted, 4 - dashdot)
-   export let title = '';                    // title of the bar series (reserved for future use)
+   ```svelte
+   <script>
+      import { Vector, cbind } from 'mdatools/arrays';
+      import { Axes, Multilines } from 'svelte-plots-basic/2d';
 
+      const xValues = Vector.seq(0, 100, 100);
+      const YY = cbind(
+         xValues.apply(v => Math.sin(v)),
+         xValues.apply(v => Math.sin(v + 0.5) + 0.1),
+         xValues.apply(v => Math.sin(v - 0.5) - 0.1),
+         xValues.apply(v => Math.sin(v + 1.0) + 0.2),
+         xValues.apply(v => Math.sin(v - 1.0) - 0.2)
+      )
+   </script>
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
+   <Axes limX={[0, 10]} limY={[-1.2, 1.2]}>
+      <Multilines {xValues} {yValues}  />
+   </Axes>
+   ```
+-->
+<script>
+   import { getContext } from 'svelte';
+   import { ismatrix } from 'mdatools/arrays';
+   import { Colors } from '../constants';
+   import { val2p, checkCoords, handleClick } from '../methods';
+   import { LINE_STYLES } from '../constants';
 
-   // get axes context
-   const axes = getContext('axes');
+   /** @type {Props} */
+   let {
+	   xValues,                       // vector or array with x-coordinates of the points
+      yValues,                       // vector or array with y-coordinates of the points
+      lineColor = Colors.PRIMARY,    // color of segment lines
+      lineType = 1,                  // type of segment lines (1 - solid, 2 - dashed, 3 - dotted, 4 - dashdot)
+      lineWidth = 1,                 // width (thickness) of segment lines
+      onclick,                       // function to be called if onclick event fires
+   } = $props();
 
-   const scale = axes.scale;
-   const isOk = axes.isOk;
-   const tX = axes.tX;
-   const tY = axes.tY;
+   // check user provided coordinates
+   const xv = $derived(checkCoords(xValues, 'Multilines'));
+   const yv = $derived.by(() => {
 
-   // compute polynomial coordinates as string
-   let pp;
-   $: if ($isOk) {
+      if (!xv) return null;
 
       if (!ismatrix(yValues)) {
-         throw Error('Multilines: parameter "yValues" must be a matrix.');
+         console.error('Multilines: parameter "yValues" must be a matrix.');
+         return null;
       }
 
-      if (xValues.length !== yValues.nrows) {
-         throw Error('Multilines: parameter "xValues" must have the same number of values as number of rows in "yValues".');
+      if (xv.length !== yValues.nrows) {
+         console.error('Multilines: parameter "xValues" must have the same number of values as number of rows in "yValues".');
       }
 
-      pp = new Array(yValues.ncols);
-      for (let i = 0; i < pp.length; i++) {
-         pp[i] = val2p(xValues, yValues.getcolumn(i + 1), $tX, $tY, axes);
+      return yValues;
+   });
+
+
+   // get axes context and compute coordinates of the polylines
+   const axes = getContext('axes');
+   const pp = $derived.by(() => {
+      if (!xv || !yv) return null;
+      const lpp = new Array(yv.ncols);
+      for (let i = 0; i < lpp.length; i++) {
+         lpp[i] = val2p(xv, yv.getcolumn(i + 1), axes.tX(), axes.tY());
       }
-   }
+      return lpp;
+   });
 
    // reactive variables for coordinates of data points in pixels
-   $: lineStyleStr = `fill:transparent;stroke:${lineColor};stroke-width: ${lineWidth}px; stroke-dasharray:${axes.LINE_STYLES[$scale][lineType-1]}`;
+   const lineStyleStr = $derived(`fill:transparent;stroke:${lineColor};stroke-width: ${lineWidth}px; stroke-dasharray:${LINE_STYLES[axes.scales().plot][lineType-1]}`);
 </script>
 
-{#if $isOk && pp !== undefined && pp.length > 0}
-   <g class="series series-multiline" style={lineStyleStr} title={title}>
-      {#each pp as p}
-      <polyline class="line" points={p}/>
-      {/each}
-   </g>
+{#if pp && pp.length > 0}
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<g  onclick={(e) => handleClick(e, 'polyline', onclick)} class="series series-multiline" style={lineStyleStr}>
+   {#each pp as p}
+   <polyline class="line" points={p}/>
+   {/each}
+</g>
 {/if}
 

package/src/2d/Points.svelte

@@ -1,68 +1,86 @@
+<!--
+@component Adds a series of points.
+
+   Main properties:
+   - `xValues` - array of vector with x-coordinates of the points.
+   - `yValues` - array of vector with y-coordinates of the points.
+   - `marker` - index for a point symbol (from 1 - default - to 8): `"●", "◼", "▲", "▼", "⬥", "＋", "*", "✕"`.
+   - `faceColor` - face (fill) color of the markers, default: `'transparent'`.
+   - `lineColor` - border color of the markers, default: `Colors.PRIMARY`.
+   - `lineWidth` - width (thickness) of the markers' border in pixels, defailt: `1`.
+   - `markerSize` - size of the markers in em, defailt: `1`.
+   - `onclick` - function (callback) to be called when user clicks on a marker.
+
+   Example:
+
+   ```svelte
+   <script>
+      import { Axes, Points } from 'svelte-plots-basic/2d';
+
+      const xValues = [-3, -2, -1, 0, 1, 2, 3];
+      const yValues = [9, 4, 1, 0, 1, 4, 9];
+   </script>
+
+   <Axes limX={[-4, 4]} limY={[-2, 10]}>
+      <Points {xValues} {yValues}  />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Points                                            *
-   * --------------------                              *
-   * shows series of points/markers on a plot          *
-   *****************************************************/
-
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-	export let xValues;                          // array of vector with x-coordinates of points
-   export let yValues;                          // array of vector with y-coordinates of points
-   export let marker = 1                        // index for point symbol (from 1 to 8): "●", "◼", "▲", "▼", "⬥", "＋", "*", "✕"
-   export let faceColor = 'transparent';        // face (fill) color of the points
-   export let borderColor = Colors.PRIMARY;     // border color of the points
-   export let borderWidth = 1;                  // width (thickness) of the points
-   export let markerSize = 1;                   // size of the marker symbols
-   export let title = '';                       // title of the point series - required for handling mouse click events
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // get axes context and adjust x margins
-   const axes = getContext('axes');
-   const tX = axes.tX;
-   const tY = axes.tY;
-   const isOk = axes.isOk;
-
-   let x, y, markerSymbol;
-
-   // reactive calculations triggered by changes in coordinates and plot parameters
-   $: if ($isOk) {
-
-      if (typeof(marker) !== "number" || marker < 1 || marker > axes.MARKER_SYMBOLS.length) {
-         throw Error(`Points: parameter "marker" must be a number from 1 to ${axes.MARKER_SYMBOLS.length}.`);
-      }
-
-      markerSymbol = axes.MARKER_SYMBOLS[marker - 1];
-
-      x = axes.transform(checkCoords(xValues, 'Points'), $tX.coords);
-      y = axes.transform(checkCoords(yValues, 'Points'), $tY.coords);
-
-      // sanity check for input parameters
-      if (x.length !== y.length) {
-         throw Error('Points: parameters "xValues" and "yValues" must be vectors of the same length.')
+   import { Colors, MARKER_SYMBOLS } from '../constants';
+   import { checkCoords, transformCoords, handleClick } from '../methods';
+
+   /** @type {Props} */
+   let {
+	   xValues,                          // array of vector with x-coordinates of points
+      yValues,                          // array of vector with y-coordinates of points
+      marker = 1,                       // index for point symbol (from 1 to 8): "●", "◼", "▲", "▼", "⬥", "＋", "*", "✕"
+      faceColor = 'transparent',        // face (fill) color of the points
+      lineColor = Colors.PRIMARY,     // border color of the points
+      lineWidth = 1,                  // width (thickness) of the points
+      markerSize = 1,                   // size of the marker symbols
+      onclick,                          // function to be called if onclick event fires
+   } = $props();
+
+
+   // select which symbol to use as a marker
+   const markerSymbol = $derived.by(() => {
+      if (typeof(marker) !== 'number' || marker < 1 || marker > MARKER_SYMBOLS.length) {
+         console.error('Points: parameter "marker" must be a number from 1 to ' + MARKER_SYMBOLS.length + '.');
+         return null;
       }
-   }
+      return MARKER_SYMBOLS[marker - 1]
+   });
 
-   // styles for the elements
-   $: textStyleStr = ['＋', '✳', '✕'].includes(markerSymbol)  ?
-       `fill:${borderColor && borderColor !== 'transparent' ? borderColor : faceColor};stroke-width:0px;font-size:${markerSize}em;` :
-       `fill:${faceColor};stroke-width:${borderWidth}px;stroke:${borderColor}; font-size:${markerSize}em;`;
+   // check user provided coordinates
+   const xv = $derived(checkCoords(xValues, 'Points'));
+   const yv = $derived(xv ? checkCoords(yValues, 'Points', xv.length) : null);
 
+   // get axes context and compute screen coordinates
+   const axes = getContext('axes');
+   const x = $derived(xv ? transformCoords(xv, axes.tX()) : null);
+   const y = $derived(x && yv ? transformCoords(yv, axes.tY()) : null);
+
+   // styles for the markers
+   const textStyleStr = $derived(['＋', '✳', '✕'].includes(markerSymbol)  ?
+       `fill:${lineColor && lineColor !== 'transparent' ? lineColor : faceColor};stroke-width:0px;font-size:${markerSize}em;` :
+       `fill:${faceColor};stroke-width:${lineWidth}px;stroke:${lineColor}; font-size:${markerSize}em;`
+   );
+
+   const alignStyleStr = $derived(['◼', '⬥', '＋', '✳', '✕'].includes(markerSymbol)  ?
+       `dominant-baseline:central;alignment-baseline:mathematical;` :
+       `dominant-baseline:middle;alignment-baseline:middle;`
+   );
+   // check if all coordinates are correct
+   const isOk = $derived(x && y && x.length === y.length);
 </script>
 
-{#if $isOk && x !== undefined && y !== undefined}
-<g class="series series-points" title={title} style={textStyleStr} dominant-baseline="middle" text-anchor="middle">
+{#if isOk}
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<g onclick={(e) => handleClick(e, 'text', onclick)}
+   class="series series-points" style={textStyleStr + alignStyleStr} text-anchor="middle">
    {#each x as v, i}
       <text x={x[i]} y={y[i]}>{markerSymbol}</text>
    {/each}

package/src/2d/Rectangles.svelte

@@ -1,70 +1,79 @@
+<!--
+@component Adds a series of rectangles.
+
+   Main properties:
+   - `left` - array or vector with world coordinates of left side of the rectangles.
+   - `top` - array or vector with world coordinates of left side of the rectangles.
+   - `width` - width of the rectangles (one value or array/vector with individual values).
+   - `height` - height of the rectangles (one value or array/vector with individual values).
+   - `facColor` - face color of the rectangles (same for all).
+   - `lineColor` - border color of each rectangle.
+   - `lineWidth` - width (thickness) of border lines in pixels.
+   - `className`- CSS class name for the labels group, default: `'series-rect'`.
+   - `onclick` - function (callback) to be called when user clicks on any rectangle.
+
+
+   Example:
+   ```jsx
+   <script>
+      import { Matrix } from 'mdatools/arrays';
+      import { Axes, Rectangles } from 'svelte-plots-basic/2d';
+
+      const left = [0, 10, 20, 30];
+      const top = [10, 20, 30, 40];
+      const width = 5;
+      const height = 10;
+   </script>
+
+   <Axes limX={[0, 40]} limY={[0, 50]}>
+      <Rectangles {left} {top} {width} {height} lineColor="red" faceColor="pink"  />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Rectangles                                        *
-   * --------------------                              *
-   * shows series of rectangles                        *
-   *****************************************************/
-
    import { getContext } from 'svelte';
    import { Vector } from 'mdatools/arrays';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-	export let left;                          // array of vector with coordinates of left sides of the bars
-   export let top;                           // array of vector with coordinates of top sides of the bars
-   export let width;                         // single value (same for all) or vector/array with bar width
-   export let height;                        // single value (same for all) or vector/array with bar height
-   export let faceColor = Colors.PRIMARY;    // color of bar faces (fill)
-   export let borderColor = faceColor;       // color of bar borders
-   export let lineWidth = 1;                 // width (thickness) of bar border lines
-   export let className = 'series-rect';     // CSS class name of the SVG group
-   export let title = '';                    // title of the rectangle series (reserved for future use)
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // get axes context and reactive variables needed to compute coordinates
+   import { Colors } from '../constants';
+   import { checkCoords, transformCoords, transformObjects, handleClick } from '../methods';
+
+   /** @type {Props} */
+   let {
+	   left,                          // array of vector with coordinates of left sides of the bars
+      top,                           // array of vector with coordinates of top sides of the bars
+      width,                         // single value (same for all) or vector/array with bar width
+      height,                        // single value (same for all) or vector/array with bar height
+      faceColor = Colors.PRIMARY,    // color of bar faces (fill)
+      lineColor = faceColor,       // color of bar borders
+      lineWidth = 1,                 // width (thickness) of bar border lines
+      className = 'series-rect',     // CSS class name of the SVG group
+      onclick,                       // function to be called if onclick event fires
+   } = $props();
+
+   // process provided values and compute world coordinates of rectangles
+   const l = $derived(checkCoords(left, 'Rectangles (left)'));
+   const t = $derived(l ? checkCoords(top, 'Rectangles (top)', l.length) : null);
+   const w = $derived(t ? (typeof width !== 'object' ? Vector.fill(width, l.length) : width) : null);
+   const h = $derived(t ? (typeof height !== 'object' ? Vector.fill(height, l.length) : height) : null);
+
+   // get axes context and compute screen coordinates
    const axes = getContext('axes');
-   const tX = axes.tX;
-   const tY = axes.tY;
-   const isOk = axes.isOk;
-
-   let rx, ry, rw, rh = undefined;
-   $: {
-      if ($isOk) {
-         rx = axes.transform(checkCoords(left, 'Rectangles'), $tX.coords);
-         ry = axes.transform(checkCoords(top, 'Rectangles'), $tY.coords);
-
-         if (rx.length !== ry.length) {
-            throw Error('Rectangles: parameters "left" and "top" must be vectors of the same length.');
-         }
 
-         if (typeof width !== 'object') {
-            width = Vector.fill(width, left.length);
-         }
-
-         if (typeof height !== 'object') {
-            height = Vector.fill(height, left.length);
-         }
-
-         rw = axes.transform(width, $tX.objects);
-         rh = axes.transform(height, $tY.objects);
-      }
-   }
+   const rx = $derived(l ? transformCoords(l, axes.tX()) : null);
+   const ry = $derived(t ? transformCoords(t, axes.tY()) : null);
+   const rw = $derived(w ? transformObjects(w, axes.tX()) : null);
+   const rh = $derived(h ? transformObjects(h, axes.tY()) : null);
 
    // styles for bars and labels
-   $: barsStyleStr = `fill:${faceColor};stroke:${borderColor};stroke-width:${lineWidth}px;`;
+   const barsStyleStr = $derived(`fill:${faceColor};stroke:${lineColor};stroke-width:${lineWidth}px;`);
+
+   // check if all coordinates are correct
+   const isOk = $derived(rx && ry && rw && rh && (rw.length === rx.length) && (rh.length === rx.length));
 </script>
 
-{#if $isOk}
-   <g class="series {className}" title={title} style={barsStyleStr}>
+{#if isOk}
+   <!-- svelte-ignore a11y_click_events_have_key_events -->
+   <!-- svelte-ignore a11y_no_static_element_interactions -->
+   <g class="series {className}"  style={barsStyleStr} onclick={(e) => handleClick(e, 'rect', onclick)} >
    {#each left as v, i}
       <rect x={rx[i]} y={ry[i]} width={rw[i]} height={rh[i]} />
    {/each}

package/src/2d/Segments.svelte

@@ -1,62 +1,75 @@
-<script>
-   /****************************************************
-   * Segments                                          *
-   * --------------------                              *
-   * shows series of line segments                     *
-   *****************************************************/
+<!--
+@component Adds a series with line segments.
 
-   import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
+   Main properties:
+   - `xStart` - vector or array with x-coordinates of starting points.
+   - `xEnd` -  or array with x-coordinates of end points.
+   - `yStart` - vector or array with y-coordinates of starting points.
+   - `yEnd` - vector or array with y-coordinates of end points.
+   - `lineColor` - color of segment lines, default: `Colors.PRIMARY`.
+   - `lineType` -  type of segment lines (`1` - solid, `2` - dashed, `3` - dotted, `4` - dashdot).
+   - `lineWidth` - width (thickness) of segment lines in pixels, default: `1`.
+   - `onclick` - function (callback) to be called when user clicks on any segment.
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   Example:
 
-	export let xStart;                        // vector or array with x-coordinates of starting points
-   export let xEnd;                          // vector or array with x-coordinates of end points
-   export let yStart;                        // vector or array with y-coordinates of starting points
-   export let yEnd;                          // vector or array with y-coordinates of end points
-   export let lineColor = Colors.PRIMARY;    // color of segment lines
-   export let lineType = 1;                  // type of segment lines (1 - solid, 2 - dashed, 3 - dotted, 4 - dashdot)
-   export let lineWidth = 1;                 // width (thickness) of segment lines
-   export let className = 'series-seg';      // CSS class name of the SVG group
-   export let title = '';                    // title of the segment series (reserved for future use)
+   ```svelte
+   <script>
+      import { Axes, Segments } from 'svelte-plots-basic/2d';
 
+      const xStart = [1, 2, 3, 4];
+      const xEnd = [1, 2, 3, 4];
+      const yStart = [-2, -1, 0, -1, -2];
+      const yEnd = [2, 1, 0, 1, 2];
+   </script>
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
+   <Axes limX={[0, 5]} limY={[-3, 3]} >
+      <Segments {xStart} {yStart} {xEnd} {yEnd} lineColor="red" lineType={2} />
+   </Axes>
+   ```
+-->
+<script>
+   import { getContext } from 'svelte';
+   import { Colors } from '../constants';
+   import { checkCoords, transformCoords, handleClick } from '../methods';
+   import { LINE_STYLES } from '../constants';
 
-   // get axes context and reactive variables needed to compute coordinates
-   const axes = getContext('axes');
-   const scale = axes.scale;
-   const isOk = axes.isOk;
-   const tX = axes.tX;
-   const tY = axes.tY;
+   let {
+	   xStart,                        // vector or array with x-coordinates of starting points
+      xEnd,                          // vector or array with x-coordinates of end points
+      yStart,                        // vector or array with y-coordinates of starting points
+      yEnd,                          // vector or array with y-coordinates of end points
+      lineColor = Colors.PRIMARY,    // color of segment lines
+      lineType = 1,                  // type of segment lines (1 - solid, 2 - dashed, 3 - dotted, 4 - dashdot)
+      lineWidth = 1,                 // width (thickness) of segment lines
+      onclick,                       // function to be called if onclick event fires
+   } = $props();
 
-   let x1, x2, y1, y2 = undefined;
-   $: {
-      if ($isOk) {
 
-         x1 = axes.transform(checkCoords(xStart, 'Segments'), $tX.coords);
-         y1 = axes.transform(checkCoords(yStart, 'Segments'), $tY.coords);
-         x2 = axes.transform(checkCoords(xEnd, 'Segments'), $tX.coords);
-         y2 = axes.transform(checkCoords(yEnd, 'Segments'), $tY.coords);
+   // check user defined coordinates
+   const sx = $derived(checkCoords(xStart, 'Segments'));
+   const sy = $derived(sx ? checkCoords(yStart, 'Segments', sx.length) : null);
+   const ex = $derived(sy ? checkCoords(xEnd, 'Segments', sx.length) : null);
+   const ey = $derived(ex ? checkCoords(yEnd, 'Segments', sx.length) : null);
 
-         const n = x1.length;
-         if (x2.length !== n || y1.length !== n || y2.length !== n) {
-            throw Error('Segments: parameters "xStart", "yStart", "xEnd" and "yEnd" should have the same length.');
-         }
-      }
-   }
+   // get axes context and reactive variables needed to compute coordinates
+   const axes = getContext('axes');
+   const x1 = $derived(sx ? transformCoords(sx, axes.tX()) : null);
+   const x2 = $derived(ex ? transformCoords(ex, axes.tX()) : null);
+   const y1 = $derived(sy ? transformCoords(sy, axes.tY()) : null);
+   const y2 = $derived(ey ? transformCoords(ey, axes.tY()) : null);
 
    // reactive variables for coordinates of data points in pixels (and line style)
-   $: lineStyleStr = `stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${axes.LINE_STYLES[$scale][lineType-1]}`;
+   const lineStyleStr = $derived(`stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scales().plot][lineType-1]}`);
+
+   // local status
+   const isOk = $derived(x1 && x2 && y1 && y2);
 </script>
 
-{#if $isOk}
-   <g class="series {className}" title={title} style={lineStyleStr}>
+{#if isOk}
+   <!-- svelte-ignore a11y_click_events_have_key_events -->
+   <!-- svelte-ignore a11y_no_static_element_interactions -->
+   <g class="series series-segment" style={lineStyleStr} onclick={(e) => handleClick(e, 'line', onclick)}>
    {#each x1 as v, i}
       <line x1={x1[i]} x2={x2[i]} y1={y1[i]} y2={y2[i]} />
    {/each}