svelte-plots-basic 2.5.8 → 3.0.1

package/src/2d/TextLabels.svelte

@@ -1,97 +1,127 @@
+<!--
+@component Adds a series with line segments.
+
+   Main properties:
+   - `xValues`- vector or array with x-coordinates for each label.
+   - `yValues`- vector or array with y-coordinates for each label.
+   - `labels`- single string or array with labels (strings).
+   - `pos`- position of labels related to coordinates (`0` - middle - default, `1` - bottom, `2` - left, `3` - top, `4` - right).
+   - `faceColor`-  face color of label symbols, default: `Colors.PRIMARY_TEXT`.
+   - `lineColor`- border colors of label symbols, default: `'transparent'`.
+   - `lineWidth`- border width of label symbols in pixels, default: `0`.
+   - `textSize`- size of label symbols in em, default: `1`.
+   - `className`- CSS class name for the labels group, default: `'series-text'`.
+   - `rotateAngle`- angle to rotate labels, default: `0`.
+   - `onclick` - function (callback) to be called when user clicks on a label.
+
+   Example:
+
+   ```svelte
+   <script>
+      import { Axes, TextLabels } from 'svelte-plots-basic/2d';
+
+      const xValues = [1, 2, 3, 4];
+      const yValues = [1, 2, 3, 4];
+      const labels = ['🤣', '😀', '😀', '🤣'];
+   </script>
+
+   <Axes limX={[0, 5]} limY={[0, 5]} >
+      <TextLabels {xValues} {yValues} {labels} />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * TextLabels component                              *
-   * --------------------                              *
-   * shows a series of text labels on the plot         *
-   *****************************************************/
-
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-   import { checkCoords } from '../Utils';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-	export let xValues;                             // vector or array with x-coordinates for each label
-   export let yValues;                             // vector or array with y-coordinates for each label
-   export let labels;                              // array with labels (strings)
-   export let pos = 0;                             // position of labels related to coordinates (middle, bottom, left, top, right)
-   export let faceColor = Colors.PRIMARY_TEXT;     // face color of label symbols
-   export let borderColor = 'transparent';         // border colors of label symbols
-   export let borderWidth = 0;                     // border width of label symbols
-   export let textSize = 1;                        // size of label symbols
-   export let className = 'series-text';           // CSS class name for the labels group
-   export let title = 'series-text';               // title of the labels SVG group
-   export let rotateAngle = 0;                     // angle to rotate labels
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // 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 { Colors } from '../constants';
+   import { checkCoords, transformCoords, handleClick } from '../methods';
+   import { LABELS_MARGIN } from '../constants';
+
+   let {
+	   xValues,                             // vector or array with x-coordinates for each label
+      yValues,                             // vector or array with y-coordinates for each label
+      labels,                              // array with labels (strings)
+      pos = 0,                             // position of labels related to coordinates (middle, bottom, left, top, right)
+      faceColor = Colors.PRIMARY_TEXT,     // face color of label symbols
+      lineColor = 'transparent',         // border colors of label symbols
+      lineWidth = 0,                     // border width of label symbols
+      textSize = 1,                        // size of label symbols
+      rotateAngle = 0,                     // angle to rotate labels
+      onclick,                             // function to be called if onclick event fires
+   } = $props();
+
+   // array with text anchors for correct positioning
    const textAnchors = ['middle', 'middle', 'start', 'middle', 'end'];
 
-   let x, y = undefined;
-   let dx = 0, dy = 0;
+   // sanity checks of coordinates provided by user
+   const xv = $derived(checkCoords(xValues, 'TextLabels'));
+   const yv = $derived(xv ? checkCoords(yValues, 'TextLabels', xv.length) : null);
 
-   // reactive calculations triggered by changes in coordinates and plot parameters
-   $: if ($isOk) {
+   // sanity check for labels
+   const l = $derived.by(() => {
+      if (!yv) return null;
 
-      if (typeof labels === 'string' && typeof pos !== 'number' ) {
-         throw Error('TextLabels: parameter "labels" is provided as single string, so "pos" must be a single number.');
+      if (Array.isArray(labels) && labels.length !== yv.length) {
+         console.error('TextLabels: number of elements in "labels" does not match number of coordinates');
+         return null;
       }
 
-      x = axes.transform(checkCoords(xValues, 'TextLabels'), $tX.coords);
-      y = axes.transform(checkCoords(yValues, 'TextLabels'), $tY.coords);
+      return labels;
+   });
 
-      // sanity check for input parameters
-      if (x.length !== y.length) {
-         throw Error('TextLabels: parameters "xValues" and "yValues" must be vectors of the same length.');
-      }
+   // sanity check for position values
+   const p = $derived.by(() => {
+      if (!l) return null;
 
-      if (Array.isArray(labels) && labels.length !== x.length ) {
-         throw Error('TextLabels: number of elements in "labels" does not match number of coordinates.');
+      if (typeof labels === 'string' && typeof pos !== 'number' ) {
+         console.error('TextLabels: parameter "labels" is provided as single string, so "pos" must be a single number.');
+         return null;
       }
-   }
 
-   // reactive calculations triggered by changes in scale
-   $: {
-      const m = axes.LABELS_MARGIN[$scale];
-      dx = [0, 0, m,  0, -m, m];
-      dy = [0, m, 0, -m, 0, m];
-   }
+      return pos;
+   })
+
+   // get axes context and compute coordinates
+   const axes = getContext('axes');
+   const x = $derived(xv && p !== null ? transformCoords(xv, axes.tX()) : null);
+   const y = $derived(yv && x ? transformCoords(yv, axes.tY()) : null);
+
+   // define x and y shifts for positioning
+   const m = $derived(LABELS_MARGIN[axes.scales().plot]);
+   const dx = $derived([0, 0, m,  0, -m, m]);
+   const dy = $derived([0, m, 0, -m, 0, m]);
 
    // styles for the elements
-   $: textStyleStr = `fill:${faceColor};stroke-width:${borderWidth}px;stroke:${borderColor};font-size:${textSize}em;`;
+   const textStyleStr = $derived(`fill:${faceColor};stroke-width:${lineWidth}px;stroke:${lineColor};font-size:${textSize}em;`);
+
+   // local status
+   const isOk = $derived(x && y && p !== null && l && x.length === y.length);
 </script>
 
-{#if $isOk && x !== undefined && y !== undefined}
-<g class="series {className}" title={title} style={textStyleStr} >
+{#if isOk}
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<g class="series series-textlabels" style={textStyleStr} onclick={(e) => handleClick(e, 'text', onclick)} >
 
    {#if typeof labels === 'string'}
-   {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos]} dy={dy[pos]}
-         transform={rotateAngle !== undefined ? `rotate(${rotateAngle}, ${x[i] + dx[pos]}, ${y[i] + dy[pos]})` : ''}
-         text-anchor={textAnchors[pos[i]]}>{@html labels}</text>
-   {/each}
+
+      {#each x as v, i}
+         <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos]} dy={dy[pos]}
+            transform={rotateAngle !== undefined ? `rotate(${rotateAngle}, ${x[i] + dx[pos]}, ${y[i] + dy[pos]})` : ''}
+            text-anchor={textAnchors[pos[i]]}>{@html labels}</text>
+      {/each}
 
    {:else if (Array.isArray(pos) || ArrayBuffer.isView(pos))}
-   {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos[i]]} dy={dy[pos[i]]} text-anchor={textAnchors[pos[i]]}>{@html labels[i]}</text>
-   {/each}
+
+      {#each x as v, i}
+         <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos[i]]} dy={dy[pos[i]]} text-anchor={textAnchors[pos[i]]}>{@html labels[i]}</text>
+      {/each}
 
    {:else}
-   {#each x as v, i}
-      <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos]} dy={dy[pos]} text-anchor={textAnchors[pos]}>{@html labels[i]}</text>
-   {/each}
+
+      {#each x as v, i}
+         <text data-id={i} x={x[i]} y={y[i]} dx={dx[pos]} dy={dy[pos]} text-anchor={textAnchors[pos]}>{@html labels[i]}</text>
+      {/each}
+
    {/if}
 </g>
 {/if}

package/src/2d/TextLegend.svelte

@@ -1,50 +1,28 @@
 <script>
-   /****************************************************
-   * TextLegend                                        *
-   * --------------------                              *
-   * shows list of several formatted text elements     *
-   *****************************************************/
-
    import { getContext } from 'svelte';
-   import { Colors } from '../Colors';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-	export let left;                                // vector/array with coordinates of lef side of each text box
-   export let top;                                 // vector/array with coordinates of top side of each text box
-   export let dx = "0";                            // horizontal margin between left size and text in 'em' units
-   export let dy = "1.25em";                       // vertical margin between elements in 'em' units
-   export let elements;                            // array with text elements (svg tags are acceptable)
-   export let faceColor = Colors.PRIMARY_TEXT;     // face color of the text symbols
-   export let borderColor = "transparent";         // border color of the text symbols
-   export let borderWidth = 0;                     // border width of the text symbols
-   export let textSize = 1;                        // size of the text symbols
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
+   import { Colors } from '../constants';
+
+   let {
+      left,                                // vector/array with coordinates of lef side of each text box
+      top,                                 // vector/array with coordinates of top side of each text box
+      dx = "0",                            // horizontal margin between left size and text in 'em' units
+      dy = "1.25em",                       // vertical margin between elements in 'em' units
+      elements,                            // array with text elements (svg tags are acceptable)
+      faceColor = Colors.PRIMARY_TEXT,     // face color of the text symbols
+      lineColor = "transparent",           // border color of the text symbols
+      lineWidth = 0,                       // border width of the text symbols
+      textSize = 1,                        // size of the text symbols
+   } = $props()
 
    const axes = getContext('axes');
-   const tX = axes.tX;
-   const tY = axes.tY;
-   const isOk = axes.isOk;
-
-   // reactive variables for coordinates of data points in pixels
-   let x, y = undefined;
-   $: if ($isOk) {
-      x = axes.transform([left], $tX.coords);
-      y = axes.transform([top], $tY.coords);
-   }
+   const x = $derived(left ? transformCoords([left], axes.tX()) : null);
+   const y = $derived(top ? transformCoords([top], axes.tY()) : null );
 
    // styles for bars and labels
-   $: textStyleStr = `fill:${faceColor};stroke-width:${borderWidth}px;stroke:${borderColor};font-size:${textSize}em;`;
+   const textStyleStr = $derived(`fill:${faceColor};stroke-width:${lineWidth}px;stroke:${lineColor};font-size:${textSize}em;`);
 </script>
 
-{#if $isOk && x !== undefined && y !== undefined && elements.length > 0}
+{#if x && y && elements.length > 0}
    <text style={textStyleStr} x={x} y={y} dx={dx} dy={dy} dominant-baseline="middle" text-anchor="start">
       {#each elements as el, i}
          <tspan {x} {dx} dy={i === 0 ? 0 : dy}>{@html el}</tspan>

package/src/2d/XAxis.svelte

@@ -1,111 +1,61 @@
+<!--
+@component Adds x-axis with ticks, label, etc.
+
+   Main properties:
+   - `label` - text label for the axis (optional).
+   - `showGrid` - logical, show or not vertical grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limX`).
+   - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
+   - `las` - orientation of tick labels (`1` - horizontal - default, `2` - vertical).
+   - `whole` - logical, show numeric tick labels as whole numbers (without decimals) or not, default: `false`.
+
+   Example:
+   ```svelte
+   <script>
+      import {Axes, XAxis} from 'svelte-plots-basic/2d';
+   </script>
+   <Axes>
+      <XAxis label="x-axis label" showGrid={true} />
+   </Axes>
+   ```
+-->
 <script>
-   /*****************************************************/
-   /* X-Axis                                            */
-   /* --------------------                              */
-   /* shows x-axis and its elements (ticks, grid, etc.) */
-   /*****************************************************/
 
    import { getContext } from 'svelte';
-   import { Vector, vector } from 'mdatools/arrays';
-   import { Colors } from '../Colors.js';
-   import { getAxisTicks, getTickLabels } from '../Utils.js';
-   import Axis from './Axis.svelte';
-
-
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
-
-   export let slot = 'xaxis';                // slot the component must be placed in (must be "xaxis")
-   export let ticks = undefined;             // vector with numeric tick positions (by default is computed automatically)
-   export let tickLabels = undefined;        // vector with labels for each tick (by default tick values will be used)
-   export let showGrid = false;              // logical, show or not grid lines
-   export let las = 1;                       // orientation of tick labels (1 - horizontal, 2 - vertical)
-   export let whole = false;                 // should the ticks be a whole number or not
-
-   export let lineColor = Colors.DARKGRAY;   // color of axis and tick lines
-   export let gridColor = Colors.MIDDLEGRAY; // color og grid lines
-   export let textColor = Colors.DARKGRAY;   // color of text tick labels
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // sanity checks of input parameters
-   if (slot !== 'xaxis') {
-      throw('Component XAxis must have "slot=\'xaxis\'" attribute.');
-   }
-
-   // get axes context and adjust x margins
+   import { text2svg, validateTicks, validateTickLabels } from '../methods';
+
+   let {
+      label,             // text label
+      showGrid = false,  // logical, show or not grid lines
+      ticks,             // vector with numeric tick positions (by default is computed automatically)
+      tickLabels,        // vector with labels for each tick (by default tick position values will be used)
+      las = 1,           // orientation of tick labels (1 - horizontal, 2 - vertical)
+      whole = false      // should the tick positions be a whole number or not.
+   } = $props();
+
+   // get axes context and send axis parameters to parent
    const axes = getContext('axes');
 
-   // get reactive variables needed to compute coordinates
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const scale = axes.scale;
-   const xscale = axes.xscale;
-   const isOk = axes.isOk;
-   const tY = axes.tY;
+   // reactive effects to validate and activate user input
+   $effect(() => {
 
-   // prepare variables for coordinates
-   let grid = [];
-   let axisLine = [];
-   let tickCoords = [];
-   let tfCoords = [];
-   let tickFactor = 0;
+      // process label text in case if there are sub or superscripts and adjust height of label correspondingly
+      const axisLabel = text2svg(label);
+      const labelHeight = axisLabel ? (axisLabel.length === label.length ? 1 : 1.4) : 0;
 
-   // compute coordinates for ticks, grid and axis line
-   $: if ($isOk) {
-
-      // compute x-coordinates of the ticks or take the ones manually specified by user
-      const ticksX = getAxisTicks(ticks, $xLim, axes.XTICK_NUM[$xscale], true, whole);
-      const tickNum = ticksX.length;
-
-      // compute tick y-coordinates (up and bottom)
-      const dY = axes.invTransform([axes.TICK_SIZE[$scale]], $tY.objects)[0];
-      const ticksY1 = Vector.fill($yLim[0], tickNum);
-      const ticksY2 = ticksY1.add(dY);
-
-      // compute coordinates for the ends of grid
-      const gridYEnd = Vector.fill($yLim[1], tickNum);
-
-      // tick labels and tick factor
-      if (ticks === undefined || tickLabels === undefined) {
-         [tickFactor, tickLabels] = getTickLabels(ticksX.v);
+      // if ticks are provided check if they are valid and preprocess them
+      let ticksProcessed, error = '';
+      if (ticks) {
+         [ticksProcessed, error] = validateTicks(ticks, axes.limX())
       }
 
-      if (tickLabels.length !== ticksX.length) {
-         throw('XAxis: "tickLabels" must be a array of the same size as ticks.')
+      // if tick labels are provided check if they are valid and preprocess them
+      if (!error && tickLabels) {
+         [tickLabels, error] = validateTickLabels(tickLabels, ticksProcessed);
       }
 
-      // combine all coordinates together
-      grid = [
-         [ticksX, ticksY1],
-         [ticksX, gridYEnd]
-      ];
-
-      axisLine = [
-         [vector([$xLim[0]]), vector([$yLim[0]])],
-         [vector([$xLim[1]]), vector([$yLim[0]])]
-      ]
-
-      tickCoords = [
-         [ticksX, ticksY2],
-         [ticksX, ticksY1]
-      ];
-
-      tfCoords = [
-         [null, null],
-         [[$xLim[1]], [ticksY1.v[tickNum - 1] - 1.5 * dY]],
-      ];
-   }
+      // activate axis
+      axes.setXAxis({show: true, error: error, label: axisLabel, ticks: ticksProcessed,
+         labelHeight, showGrid, las, whole, tickLabels});
+   });
 </script>
-
-{#if $isOk && axisLine.length > 0}
-<Axis
-   className="mdaplot__xaxis" pos={1}
-   {lineColor} {gridColor} {textColor} {showGrid} {grid} {axisLine}
-   {tickCoords} {tickLabels} {tfCoords} {tickFactor} {las}
-/>
-{/if}

package/src/2d/YAxis.svelte

@@ -1,111 +1,64 @@
+<!--
+@component Adds y-axis with ticks, label, etc.
+
+   Main properties:
+   - `label` - text label for the axis (optional).
+   - `showGrid` - logical, show or not horizontal grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limX`).
+   - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
+   - `las` - orientation of tick labels (`1` - horizontal - default, `2` - vertical).
+   - `whole` - logical, show numeric tick labels as whole numbers (without decimals) or not, default: `false`.
+
+   Example:
+   ```svelte
+   <script>
+      import {Axes, YAxis} from 'svelte-plots-basic/2d';
+   </script>
+   <Axes>
+      <YAxis label="y-axis label" showGrid={true} />
+   </Axes>
+   ```
+-->
 <script>
-   /****************************************************
-   * Y-Axis                                            *
-   * --------------------                              *
-   * shows y-axis and its elements (ticks, grid, etc.) *
-   *****************************************************/
 
    import { getContext } from 'svelte';
-   import { Vector, vector } from 'mdatools/arrays';
-   import { Colors } from '../Colors.js';
-   import { getAxisTicks, getTickLabels } from '../Utils.js';
-   import Axis from './Axis.svelte';
+   import { text2svg, validateTicks, validateTickLabels } from '../methods';
 
 
-   /*****************************************/
-   /* Input parameters                      */
-   /*****************************************/
+   let {
+      label,             // text label
+      ticks,             // vector with numeric tick positions (by default is computed automatically)
+      tickLabels,        // vector with labels for each tick (by default tick values will be used)
+      showGrid = false,  // logical, show or not grid lines
+      las = 1,           // orientation of tick labels (1 - horizontal, 2 - vertical)
+      whole = false      // should the ticks be a whole number or not
+   } = $props();
 
-   export let slot = 'yaxis';                // slot the component must be placed in (must be "yaxis")
-   export let ticks = undefined;             // vector with numeric tick positions (by default is computed automatically)
-   export let tickLabels = undefined;        // vector with labels for each tick (by default tick values will be used)
-   export let showGrid = false;              // logical, show or not grid lines
-   export let las = 1;                       // orientation of tick labels (1 - horizontal, 2 - vertical)
-   export let whole = false;                 // should the ticks be a whole number or not
 
-   export let lineColor = Colors.DARKGRAY;   // color of axis and tick lines
-   export let gridColor = Colors.MIDDLEGRAY; // color og grid lines
-   export let textColor = Colors.DARKGRAY;   // color of text tick labels
-
-
-   /*****************************************/
-   /* Component code                        */
-   /*****************************************/
-
-   // sanity checks of input parameters
-   if (slot !== 'yaxis') {
-      throw('Component YAxis must have "slot=\'yaxis\'" attribute.');
-   }
-
-   // get axes context and adjust x margins
+   // get axes context and send axis parameters to parent
    const axes = getContext('axes');
 
-   // get reactive variables needed to compute coordinates
-   const xLim = axes.xLim;
-   const yLim = axes.yLim;
-   const scale = axes.scale;
-   const yscale = axes.yscale;
-   const isOk = axes.isOk;
-   const tX = axes.tX;
-
-   // prepare variables for coordinates
-   let grid = [];
-   let axisLine = [];
-   let tickCoords = [];
-   let tfCoords = [];
-   let tickFactor = 0;
-
-   // compute tick x-coordinates
-   $: if ($isOk) {
+   // reactive effects to validate and activate user input
+   $effect(() => {
 
-      // compute x-coordinates of the ticks or take the ones manually specified by user
-      const ticksY = getAxisTicks(ticks, $yLim, axes.YTICK_NUM[$yscale], true, whole);
-      const tickNum = ticksY.length;
+      // process label text in case if there are sub or superscripts and adjust height of label correspondingly
+      const axisLabel = text2svg(label);
+      const labelHeight = axisLabel ? (axisLabel.length === label.length ? 1.0 : 1.4) : 0;
 
-      // compute tick y-coordinates (up and bottom)
-      const dX = axes.invTransform([axes.TICK_SIZE[$scale]], $tX.objects)[0];
-      const ticksX1 = Vector.fill($xLim[0], tickNum)
-      const ticksX2 = ticksX1.add(dX)
 
-      // coordinates for the ends of grid
-      const gridXEnd = Vector.fill($xLim[1], tickNum);
-
-      // tick labels and tick factor
-      if (ticks === undefined || tickLabels === undefined) {
-         [tickFactor, tickLabels] = getTickLabels(ticksY.v)
+      // if ticks are provided check if they are valid and preprocess them
+      let ticksProcessed, error = '';
+      if (ticks) {
+         [ticksProcessed, error] = validateTicks(ticks, axes.limY())
       }
 
-      if (tickLabels.length !== ticksY.length) {
-         throw('YAxis: "tickLabels" must be a array of the same size as ticks.')
+      // if tick labels are provided check if they are valid and preprocess them
+      if (!error && tickLabels) {
+         [tickLabels, error] = validateTickLabels(tickLabels, ticksProcessed);
       }
 
-      // combine all coordinates together
-      grid = [
-         [ticksX1, ticksY],
-         [gridXEnd, ticksY]
-      ];
-
-      axisLine = [
-         [vector([$xLim[0]]), vector([$yLim[0]])],
-         [vector([$xLim[0]]), vector([$yLim[1]])]
-      ]
-
-      tickCoords = [
-         [ticksX1, ticksY],
-         [ticksX2, ticksY]
-      ];
-
-      tfCoords = [
-         [[], []],
-         [[ticksX2.v[tickNum - 1] + dX], [$yLim[1]]],
-      ];
-   }
+      // activate axis
+      axes.setYAxis({show: true, error: error, label: axisLabel, ticks: ticksProcessed,
+         labelHeight, showGrid, las, whole, tickLabels, pos: 4});
+   });
 </script>
-
-{#if $isOk && axisLine.length > 0}
-<Axis
-   className="mdaplot__yaxis" pos={4}
-   {lineColor} {gridColor} {textColor} {showGrid} {grid} {axisLine}
-   {tickCoords} {tickLabels} {tfCoords} {tickFactor} {las}
-/>
-{/if}

package/src/2d/index.js

@@ -18,4 +18,5 @@ export { default as Legend } from './Legend.svelte';
 export { default as TextLegend } from './TextLegend.svelte';
 export { default as ColormapLegend } from './ColormapLegend.svelte';
 
-export { getcolmap, Colors } from '../Colors.js';
+export { getcolmap } from '../methods.js';
+export { Colors } from '../constants.js';