svelte-plots-basic 2.5.8 → 3.0.0

package/src/2d/AxisLines.svelte

@@ -1,51 +1,52 @@
+<!--
+@component Draws line segments for axis elements (axis, ticks, etc.).
+
+   Main properties:
+   - `lineCoords` - coordinates of the line segments as 2D array.
+   - `lineColor` - color of the box line, default: `Colors.DARKGRAY`.
+   - `lineWidth` - width of box line in pixels, default: `1`.
+   - `lineType` - line type (`1` - solid (default), `2` - dashed, `3` - dotted, `4` - dashdot).
+   - `className` - string with classname to be added to `<g></g>` tag wrapping the lines.
+
+   **Description:**
+
+   The coordinates msut be provided in form of nested arrays. Each element of this array contains
+   `Vector` or `Array` with the coordinates in world (not screen) coordinate system:
+   - `lineCoords[0][0]` - x-coordinates of start points of segments.
+   - `lineCoords[1][0]` - x-coordinates of end points of segments.
+   - `lineCoords[0][1]` - y-coordinates of start points of segments.
+   - `lineCoords[1][1]` - y-coordinates of end points of segments.
+
+   ```
+-->
 <script>
-   /****************************************************
-   * Axis lines                                        *
-   * --------------------                              *
-   * generic component for axis lines (main, grid, ...)*
-   * !!! not for users !!!                             *
-   *****************************************************/
-
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors.js';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   import { Colors, LINE_STYLES } from '../constants.js';
+   import { transformCoords } from '../methods.js';
 
-   export let lineCoords = [];               // coordinates of start and end points of the lines
-   export let lineColor = Colors.DARKGRAY;   // line color
-   export let lineType = 1;                  // line type
-   export let lineWidth = 1;                 // lined width (thickness)
-   export let className = '';                // CSS class name for the component
 
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
+   let {
+      lineCoords = [],               // coordinates of start and end points of the lines
+      lineColor = Colors.DARKGRAY,   // line color
+      lineType = 1,                  // line type
+      lineWidth = 1,                 // lined width (thickness)
+      className = ''                 // CSS class name for the component
+   } = $props();
 
    // get axes context and adjust x margins
    const axes = getContext('axes');
-   const scale = axes.scale;
-   const tX = axes.tX;
-   const tY = axes.tY;
 
    // reactive variables for coordinates of axis lines
-   let x1, x2, y1, y2 = undefined;
-   $: if (lineCoords.length == 2) {
-      x1 = axes.transform(lineCoords[0][0], $tX.coords);
-      y1 = axes.transform(lineCoords[0][1], $tY.coords);
-      x2 = axes.transform(lineCoords[1][0], $tX.coords);
-      y2 = axes.transform(lineCoords[1][1], $tY.coords);
-   }
-
-   /* styles for axis and grid lines */
-   $: lineStyleStr = `stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${axes.LINE_STYLES[$scale][lineType-1]}`;
+   let x1 = $derived(transformCoords(lineCoords[0][0], axes.tX()));
+   let x2 = $derived(transformCoords(lineCoords[1][0], axes.tX()));
+   let y1 = $derived(transformCoords(lineCoords[0][1], axes.tY()));
+   let y2 = $derived(transformCoords(lineCoords[1][1], axes.tY()));
 
+   // line style
+   let lineStyleStr = $derived(`stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scales().plot][lineType-1]}`);
 </script>
 
-{#if x1 !== undefined && y1 !== undefined && x2 !== undefined && y2 !== undefined}
+{#if x1 && y1 && x2 }
 <g class={className}>
    {#each x1 as v, i}
    <line vector-effect="non-scaling-stroke" x1={x1[i]} x2={x2[i]} y1={y1[i]} y2={y2[i]} style={lineStyleStr} />

package/src/2d/AxisTickLabels.svelte

@@ -1,66 +1,59 @@
-<script>
-   /****************************************************
-   * AxisTickLabels                                    *
-   * --------------------                              *
-   * shows a series of tick labels along an axis       *
-   * !!! not for users !!!                             *
-   *****************************************************/
-
-   import { getContext } from 'svelte';
-
+<!--
+@component Adds axis tick labels.
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   Main properties:
+   - `tickCoords` - coordinates of the positions of the ticks line segments in world coordinates.
+   - `textColor` - color of the labels' text.
+   - `tickLabels` - array with the labels (strings).
+   - `pos` - position of the labels related to coordinates (`0` - on, `1` - under - default, `2` - left, `3` - over, `4` - right).
+   - `las` - orientation of the labels (`1` - horizontal - default, `2` - vertical).
 
-	export let tickCoords;  // array with tick coordinates
-   export let textColor;   // color of tick labels
-   export let tickLabels;  // array with tick labels
-   export let pos = 1;     // position of tick labels
-   export let las = 1;     // rotation of tick labels (1 - horizontal, 2 - vertical)
+   **Description:**
 
+   The ticks coordinates are provided in form of nested arrays. Each element of this array contains
+   `Vector` or `Array` with the coordinates in world (not screen) coordinate system:
+   - `tickCoords[0][0]` - x-coordinates of start points of tick segments.
+   - `tickCoords[1][0]` - x-coordinates of end points of tick segments.
+   - `tickCoords[0][1]` - y-coordinates of start points of tick segments.
+   - `tickCoords[1][1]` - y-coordinates of end points of tick segments.
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
+   ```
+-->
+<script>
 
-   // get axes context and reactive variables needed to compute coordinates
-   const axes = getContext('axes');
-   const scale = axes.scale;
-   const tX = axes.tX;
-   const tY = axes.tY;
-   const isOk = axes.isOk;
+   import { getContext } from 'svelte';
+   import { transformCoords } from '../methods';
+   import { LABELS_MARGIN } from '../constants';
 
-   let el;
 
-   let x, y = undefined;
-   let dx = 0, dy = 0, textAnchor;
+   let {
+	   tickCoords,  // nested array with tick coordinates
+      textColor,   // color of tick labels
+      tickLabels,  // array with tick labels
+      pos = 1,     // position of tick labels
+      las = 1,     // rotation of tick labels (1 - horizontal, 2 - vertical)
+   } = $props();
 
-   // reactive calculations triggered by changes in coordinates and plot parameters
-   $: if ($isOk) {
-      x = axes.transform(tickCoords[1][0], $tX.coords);
-      y = axes.transform(tickCoords[1][1], $tY.coords);
-   }
 
-   // reactive calculations triggered by changes in scale
-   $: m = axes.LABELS_MARGIN[$scale];
+   // reactive selection of labels' position and line style
+   let textAnchor = $derived((['middle', 'middle', 'start', 'middle', 'end'])[pos]);
+   let textStyleStr = $derived(`fill:${textColor};`);
 
-   // reactive calculations triggered by changes in pos
-   $: {
-      textAnchor = (['middle', 'middle', 'start', 'middle', 'end'])[pos];
-      dx = ([0, 0, m,  0, -m])[pos];
-      dy = ([0, m, 0, -m, 0])[pos];
-   }
+   // get axes context and compute screen coordinates
+   const axes = getContext('axes');
+   let x = $derived(transformCoords(tickCoords[1][0], axes.tX()));
+   let y = $derived(transformCoords(tickCoords[1][1], axes.tY()));
 
-   // styles for the elements
-   $: textStyleStr = `fill:${textColor};`;
+   // compute coordinate shifts based on position and plot scales
+   let m = $derived(LABELS_MARGIN[axes.scales().plot]);
+   let dx = $derived(([0, 0, m,  0, -m])[pos]);
+   let dy = $derived(([0, m, 0, -m, 0])[pos]);
 </script>
 
-{#if x !== undefined && y !== undefined}
-<g class="tick-labels" bind:this={el} style={textStyleStr} >
+<g class="tick-labels" style={textStyleStr} >
    {#if las === 2 && pos === 4}
    {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={0} dy={dx*1.25} transform={`rotate(-90, ${x[i]}, ${y[i]})`} text-anchor={"middle"}>{@html tickLabels[i]}</text>
+      <text data-id={i} x={x[i]} y={y[i]} dx={0} dy={dx*1.25} transform={`rotate(-90, ${x[i]}, ${y[i]})`} text-anchor="middle">{@html tickLabels[i]}</text>
    {/each}
    {:else if las === 2 && pos === 1}
    {#each x as v, i}
@@ -72,4 +65,3 @@
    {/each}
    {/if}
 </g>
-{/if}

package/src/2d/Bars.svelte

@@ -1,65 +1,120 @@
+<!--
+@component Adds a series of bars.
+
+   Main properties:
+   - `xValues` - vector with x-coordinates of middle points of the bars.
+   - `yValues` - vector with y-coordinates of top points of the bars.
+   - `barWidth` - width of bars as per cent of maximum width, defaul: `0.8`.
+   - `faceColor` - face color of the bars, default:  `Colors.PRIMARY`.
+   - `lineColor` - border color of the bars, default: `Colors.PRIMARY`.
+   - `lineWidth` - width (thickness) of border line in pixels, default: `1`.
+   - `onclick` - function (callback) to be called when user clicks on any bar.
+
+   Example:
+
+   ```svelte
+   <script>
+      import { Matrix } from 'mdatools/arrays';
+      import { Axes, Bars } from 'svelte-plots-basic/2d';
+
+      const xValues = [2000, 2010, 2020, 2030, 2040];
+      const yValues = [1, 100, 200, 300, -150];
+   </script>
+
+   <Axes limX={[1990, 2050]} limY={[-200, 350]}>
+      <Bars {xValues} {yValues} lineColor="red" faceColor="pink" />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Bars                                              *
-   * --------------------                              *
-   * shows series of bars on a plot                    *
-   *****************************************************/
-
-   import { max, diff } from 'mdatools/stat';
    import { Vector } from 'mdatools/arrays';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
+   import { Colors } from '../constants';
+   import { checkCoords } from '../methods';
 
    import Rectangles from './Rectangles.svelte';
 
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-	export let xValues;                       // vector with x-coordinates of middle points of the bars
-   export let yValues;                       // vector with y-coordinates of top points of the bars
-   export let barWidth = 0.8;                // width of bars as per cent of maximum width
-   export let faceColor = Colors.PRIMARY;    // face color of the bars
-   export let borderColor = Colors.PRIMARY;  // border color of the bars
-   export let title = '';                    // title of the bar series (reserved for future use)
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   let width, left, top, height;
-
-   // reactive code for computing position of left sides and bar width
-   $: {
-
-      if (!barWidth) {
-         barWidth = 0.8;
-      }
+   /** @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.
+      barWidth = 0.8,                // width of bars as per cent of maximum width, defaul: `0.8`.
+      barWidthExact,                 // 100% bar width in world coordinates (if not provided computed automatically).
+      faceColor = Colors.PRIMARY,    // face color of the bars, default:  `Colors.PRIMARY`.
+      lineColor = Colors.PRIMARY,  // border color of the bars, default: `Colors.PRIMARY`.
+      lineWidth = 1,               // width (thickness) of border line in pixels, default: 1.
+      onclick
+   } = $props();
 
+   const bw = $derived.by(() => {
       if (barWidth <= 0 || barWidth > 1) {
-         throw Error('BarSeries: parameters "barWidth" should be between 0 and 1.');
+         console.error('Bars: parameter "barWidth" should be between 0 and 1.');
+         return null;
       }
+      return barWidth;
+   });
 
-      // compute maximum bar width and position of left side
+   const x = $derived.by(() => {
+      if (!bw) return null;
       const xv = checkCoords(xValues, 'BarSeries');
-      const w = max(diff(xv.v)) * barWidth;
-      left = xv.subtract(w/2);
-      width = Vector.fill(w, xv.length);
-   }
+      if (!xv) return null;
+      const n = xv.length;
+      if (n < 1) return null;
+
+      let w;
+      if (barWidthExact) {
+         w = barWidthExact;
+      } else if (n == 1) {
+         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;
+         for (let i = 1; i < n; i++) {
+            lw = Math.abs(xv.v[i - 1] - xv.v[i]);
+            if (lw > w) w = lw;
+         }
+      }
+
+      w = w * barWidth;
+      const whalf = w / 2;
+      const left = Vector.zeros(n);
+      const width = Vector.zeros(n);
+      for (let i = 0; i < n; i++) {
+         left.v[i] = xv.v[i] - whalf;
+         width.v[i] = w;
+      }
 
-   // reactive code for computing position of top sides and bar height
-   $: {
+      return {left, width};
+   })
 
+   const y = $derived.by(() => {
+      if (!x) return null;
       const yv = checkCoords(yValues, 'BarSeries');
-      if (yv.length !== left.length) {
-         throw Error('BarSeries: parameters "yValues" must be vector of the same length as "xValues".');
+      if (!yv) return null;
+      const n = yv.length;
+      if (n !== x.left.length) {
+         console.error('BarSeries: parameters "yValues" must be vector of the same length as "xValues".');
+         return null;
       }
 
-      top = yv.apply(v => v > 0 ? v : 0);
-      height = yv.apply(v => Math.abs(v));
-   }
+      const top = Vector.zeros(n);
+      const height = Vector.zeros(n);
+
+      for (let i = 0; i < n; i++) {
+         const v = yv.v[i];
+         top.v[i] = (v > 0 ? v : 0);
+         height.v[i] = Math.abs(v);
+      }
+
+      return {top, height};
+   })
+
+   // local check
+   const isOk = $derived(x && y);
 </script>
 
-<Rectangles className="series-bar" {left} {top} {width} {height} {borderColor} {faceColor} {title} />
+{#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}

package/src/2d/Box.svelte

@@ -1,48 +1,28 @@
+<!--
+@component Shows box around axes.
+
+   Main properties:
+   - `lineWidth` - width of box line in pixels, default: `1`.
+   - `lineColor` - color of the box line, default: `'#606060'`.
+
+   Example:
+   ```svelte
+   <script>
+      import {Axes, Box} from 'svelte-plots-basic/2d';
+   </script>
+   <Axes>
+      <Box />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Box                                               *
-   * --------------------                              *
-   * shows border box around axes                      *
-   *****************************************************/
-
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-   export let slot;  // slot name, must be "box"
-
 
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // check that the box is located in a correct slot
-   if (slot !== 'box') {
-      throw('Component Box must have \'slot="box"\' attribute.')
-   }
-
-
-   // get axes context and reactive variables needed to compute coordinates
+   let {lineWidth = 1, lineColor = '#606060'} = $props();
    const axes = getContext('axes');
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const isOk = axes.isOk;
-   const tX = axes.tX;
-   const tY = axes.tY;
-
-   // reactive variables for coordinates of box points in pixels
-   $: xx = $isOk ? axes.transform($xLim, $tX.coords) : undefined;
-   $: yy = $isOk ? axes.transform($yLim, $tY.coords) : undefined;
 
+   $effect(() => {
+      axes.setBox({show:true, lineWidth, lineColor});
+   });
 </script>
 
-{#if $isOk}
-   <g style="pointer-events:none" class="mdaplot__axes-box">
-   <rect stroke="{Colors.DARKGRAY}" stroke-width="0.1em" fill="transparent" x={xx[0]} y={yy[1]} width={xx[1] - xx[0]} height={yy[0] - yy[1]} />
-   </g>
-{/if}
-

package/src/2d/ColormapLegend.svelte

@@ -1,121 +1,57 @@
+<!--
+@component Adds colormap legend.
+
+   Main properties:
+   - `breaks` - array (or vector) with interval breaks boundaries.
+   - `colmap` - array with colors for each break.
+   - `labels` - array with the labels (strings) for breaks or boundaries (optional).
+   - `labelColor` - color of labels, default: `Colors.CLEGEND_LABELS`.
+   - `fontSize` - font size for the labels in em, default `0.85`.
+
+   **Description:**
+
+   Shows legend as a sequence of colors from `colormap` which correspond to the breaks. Number of
+   colors must be equal to the number of elements in array `breaks` minus one.
+
+   The labels can correspond to each value of the `breaks` array (boundaries) or to each break.
+   In the latter the labels will be shown in the middle of each break. If `labels` are not provided,
+   the values from `breaks` will be used as the labels.
+
+   Example:
+
+   ```svelte
+   <script>
+      import { Axes, ColormapLegend } from 'svelte-plots-basic/2d';
+
+      const breaks = [0, 1, 2, 3, 4];
+      const colmap = ['blue', 'green', 'orange', 'red'];
+      const labels = ['A', 'B', 'C', 'D'];
+   </script>
+   <Axes>
+      // all other plotting components are here
+      <ColormapLegend {breaks} {colmap} {labels} />
+   </Axes>
+   ```
+-->
 <script>
-   /*********************************************************
-   * ColormapLegend                                         *
-   * --------------------                                   *
-   * shows color map legend on a plot                       *
-   **********************************************************/
-
    import { getContext } from 'svelte';
-   import { checkCoords, getTickLabels, getTickFactorLabel } from '../Utils';
-   import { Vector, isvector } from 'mdatools/arrays';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-   export let breaks;                  // vector with breaks for color intervals or vector with their indices
-   export let colmap;                  // array with colors for each interval
-   export let decNum = 1;              // number of decimals to show the interval boundaries with
-   export let labels = null;           // optional vector with labels for interval boundaries or elements
-   export let labelColor = '#909090';  // color of labels
-   export let fontSize = 0.85;         // font size for labels in em
-
-   // if number of breaks is the same as number of elements in color map
-   // the corresponding labels will be placed in the middle inder each color element in the legend
-   // if this number is by one larger, the labels will be placed on the boundaries
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // constant parameters
-   const WIDTH_RATIO = 0.80;    // legend will span 80% of plot width
-   const HEIGHT_RATIO = 0.02;   // legend will span 2% of plot height
-   const TOP_MARGIN = 0.25;     // legend top margin is 25% of its height
-
-   // height of the legend elements in pixels
-   const EL_HEIGHTS_PX = {'small': 5, 'medium': 8, 'large': 12, 'xlarge': 15};
-
-   // check breaks values
-   $: if (!breaks || breaks.length < 2) {
-      throw new Error('ColormapLegend: breaks values must be provided.');
-   }
-
-   // check colormap values
-   $: if (!colmap || !(colmap.length === breaks.length - 1 || colmap.length === breaks.length )) {
-      throw new Error('ColormapLegend: number of color values in colormap does not match number of intervals defined by breaks.');
-   }
+   import { Colors } from '../constants';
 
-   // define local variables for breaks and prepare breaks labels
-   $: lBreaks = isvector(breaks) ? breaks.v : breaks;
 
-   let breakFactor, breakLabels;
-   $: if (lBreaks) {
-      [breakFactor, breakLabels] = getTickLabels(lBreaks);
-   } else {
-      breakFactor = null;
-      breakLabels = null;
-   }
+   let {
+      breaks,                                // vector with breaks for color intervals or vector with their indices
+      colmap,                                // array with colors for each interval
+      labels = null,                         // optional vector with labels for interval boundaries or elements
+      labelColor = Colors.CLEGEND_LABELS,    // color of labels
+      fontSize = 0.85,                       // font size for labels in em
+   } = $props();
 
-   $: lLabels = labels && labels.length === lBreaks.length ? labels : breakLabels;
-
-   // get axes context and reactive variables needed to compute coordinates
+   // get axes context and set the parameters of colormap legend (the rest will be done by Axes component)
    const axes = getContext('axes');
-   const tX = axes.tX;
-   const tY = axes.tY;
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const scale = axes.scale;
-   const isOk = axes.isOk;
-
-   // number of elements
-   $: n = colmap.length;
-   $: isCentered = lLabels && lLabels.length === n;
-
-   // compute screen coordinates of the elements
-   let dxl, rx, ry, rw, rh = undefined;
-   $: {
-      if ($isOk) {
-         // compute size of the whole block in plot coordinates
-         const axesWidth = $xLim[1] - $xLim[0];
-         const axesHeight = $yLim[1] - $yLim[0];
-         const width = axesWidth * WIDTH_RATIO;
-         const height = axesHeight * HEIGHT_RATIO;
-
-         // compute elements size and position
-         const elWidth = width / (n + (breakFactor !== 0));
-         const left = $xLim[0] + axesWidth * (1 - WIDTH_RATIO) * 0.5 ;
-         const elTop = $yLim[1] - height * TOP_MARGIN;
-
-         // compute screen coordinates and sized
-         ry = axes.transform(checkCoords([elTop], 'Rectangles'), $tY.coords);
-         rx = axes.transform(Vector.seq(0, n).apply(v => left + v * elWidth), $tX.coords);
-         rw = axes.transform([elWidth], $tX.objects);
-         rh = EL_HEIGHTS_PX[$scale];
-         dxl = isCentered ? rw[0] / 2 : 0
-      }
-   };
+   $effect(() => {
+      axes.setColmapLegend({show: true, breaks, colmap, labels, labelColor, fontSize})
+   });
 </script>
 
-{#if $isOk && rx.length > 0}
-   <g class="series colormap_legend" style="stroke:0;stroke-width:0px;">
-   {#each colmap as col, i}
-      <rect x={rx[i]} y={ry} width={rw} height={rh} fill="{col}"/>
-      <text x={rx[i]} y={ry} dx={dxl} dy={rh * 1.25} dominant-baseline="hanging" fill={labelColor} font-size="{fontSize}em" text-anchor="middle">{@html lLabels[i]}</text>
-   {/each}
-   {#if !isCentered}
-   <text x={rx[n]} y={ry} dx={0} dy={rh * 1.25} dominant-baseline="hanging" fill={labelColor} font-size="{fontSize}em" text-anchor="middle">{@html lLabels[n]}</text>
-   {/if}
-
-   {#if breakFactor !== 0}
-   <text x={rx[n] + rw[0] * 0.85} y={ry[0] + rh * 2.2} dx={0} dy={0} dominant-baseline="hanging" fill={labelColor} font-size="{fontSize}em" text-anchor="middle">{@html getTickFactorLabel(breakFactor)}</text>
-   {/if}
-
-   </g>
-
-
-{/if}
-