svelte-plots-basic 3.4.0 → 4.1.0

package/src/3d/Lines.svelte

@@ -2,16 +2,16 @@
 @component Adds a series of lines connecting points with provided coordinates (polyline).
 
    Main properties:
-   - `xValues` - array of vector with x-coordinates of the points.
-   - `yValues` - array of vector with y-coordinates of the points.
-   - `zValues` - array of vector with z-coordinates of the points.
+   - `xValues` - array or vector with x-coordinates of the points.
+   - `yValues` - array or vector with y-coordinates of the points.
+   - `zValues` - array or vector with z-coordinates of the points.
    - `lineColor` - lines color, default: `Colors.PRIMARY`.
-   - `lineWidth` - width (thickness) of the lines in pixels, defailt: `1`.
+   - `lineWidth` - width (thickness) of the lines in pixels, default: `1`.
    - `lineType` -  type of lines (`1` - solid, `2` - dashed, `3` - dotted, `4` - dashdot).
    - `title` - title of the line series group.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import { Axes, Lines } from 'svelte-plots-basic/3d';
 
@@ -29,7 +29,7 @@
    import { cbind } from 'mdatools/arrays';
    import { getContext } from 'svelte';
    import { Colors, LINE_STYLES } from '../constants';
-   import { checkCoords, transform3D } from '../methods';
+   import { checkCoords, transform3D, normalizeLineType } from '../methods';
 
    let {
 	   xValues,
@@ -55,6 +55,7 @@
    const ux = $derived(checkCoords(xValues, 'Lines (3D)'));
    const uy = $derived(ux ? checkCoords(yValues, 'Lines (3D)', ux.length) : null);
    const uz = $derived(uy ? checkCoords(zValues, 'Lines (3D)', ux.length) : null);
+   const validLineType = $derived(normalizeLineType(lineType, 'Lines (3D)'));
 
    // combine world coordinates to matrices
    const uW = $derived(ux && uy && uz ? cbind(ux, uy, uz) : null);
@@ -65,7 +66,7 @@
    const p = $derived(s ? coords2points(s) : null);
 
    // reactive variables for coordinates of data points in pixels
-   const lineStyleStr = $derived(`fill:transparent;stroke:${lineColor};stroke-width: ${lineWidth}px; stroke-dasharray:${LINE_STYLES[axes.scale()][lineType-1]}`);
+   const lineStyleStr = $derived(`fill:transparent;stroke:${lineColor};stroke-width: ${lineWidth}px; stroke-dasharray:${LINE_STYLES[axes.scale()][validLineType - 1]}`);
 </script>
 
 {#if p}
@@ -73,4 +74,3 @@
       <polyline class="line" points={p}/>
    </g>
 {/if}
-

package/src/3d/Mesh.svelte

@@ -1,20 +1,20 @@
 <!--
-@component Adds a mesh plot as a set of grid points and line segments connected them.
+@component Adds a mesh plot as a set of grid points and line segments connecting them.
 
    Main properties:
-   - `xValues` - array of vector with x-coordinates of the mesh points.
-   - `zValues` - array of vector with z-coordinates of the mesh points.
+   - `xValues` - array or vector with x-coordinates of the mesh points.
+   - `zValues` - array or vector with z-coordinates of the mesh points.
    - `yValues` - matrix (!) with y-coordinates of the points defining its height.
-   - `colmap` - array with colors to use for different height.
-   - `lineWidth` - width (thickness) of the lines in pixels, defailt: `1`.
+   - `colmap` - array with colors to use for different heights.
+   - `lineWidth` - width (thickness) of the lines in pixels, default: `1`.
    - `lineType` -  type of lines (`1` - solid, `2` - dashed, `3` - dotted, `4` - dashdot).
-   - `title` - title of the line series group.
+   - `title` - title of the mesh series group.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
-      import { Axes, Mesh } from 'svelte-plots-basic/3d';
-      import { gecolmap } from 'svelte-plots-basic/utils';
+      import { Axes, Mesh, getcolmap } from 'svelte-plots-basic/3d';
+      import { Matrix, Vector } from 'mdatools/arrays';
 
       const xMesh = Vector.seq(-8, 8, 1);
       const zMesh = Vector.seq(-8, 8, 1);
@@ -24,6 +24,7 @@
    <Axes limX={[-10, 10]} limY={[-10, 10]} limZ={[-10, 10]}>
       <Mesh xValues={xMesh} yValues={yMesh} zValues={zMesh} colmap={getcolmap(16)}/>
    </Axes>
+   ```
 -->
 <script>
 
@@ -31,7 +32,7 @@
    import { range } from 'mdatools/stat';
    import { getContext } from 'svelte';
    import { Colors, LINE_STYLES } from '../constants';
-   import { checkCoords, transform3D } from '../methods';
+   import { checkCoords, transform3D, normalizeLineType } from '../methods';
 
    let {
       title = '',
@@ -46,6 +47,7 @@
    // check user defined coordinates
    const ux = $derived(checkCoords(xValues, 'Mesh (3D)'));
    const uz = $derived(ux ? checkCoords(zValues, 'Mesh (3D)') : null);
+   const validLineType = $derived(normalizeLineType(lineType, 'Mesh (3D)'));
    const Uy = $derived.by(() => {
       if (!ux || !uz) return null;
       if (!ismatrix(yValues)) {
@@ -184,16 +186,16 @@
    const s2s = $derived(mesh ? transform3D(mesh.M2s, axes.tM()) : null);
    const s2e = $derived(mesh ? transform3D(mesh.M2e, axes.tM()) : null);
 
-   const lineStyleStr = $derived(`stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scale()][lineType-1]};`);
+   const lineStyleStr = $derived(`stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scale()][validLineType - 1]};`);
 </script>
 
-<g class="series series_mesh" style={lineStyleStr} data-title={title}>
 {#if s1s && s1e && s2s && s2e }
+<g class="series series_mesh" style={lineStyleStr} data-title={title}>
    {#each s1s.x as v, i}
    <line x1={s1s.x[i]} x2={s1e.x[i]} y1={s1s.y[i]} y2={s1e.y[i]} style={`stroke:${colors[mesh.color1.v[i]]};`} />
    {/each}
    {#each s2s.x as v, i}
    <line x1={s2s.x[i]} x2={s2e.x[i]} y1={s2s.y[i]} y2={s2e.y[i]} style={`stroke:${colors[mesh.color2.v[i]]};`} />
    {/each}
-{/if}
 </g>
+{/if}

package/src/3d/Points.svelte

@@ -2,18 +2,18 @@
 @component Adds a series of points (markers).
 
    Main properties:
-   - `xValues` - array of vector with x-coordinates of the points.
-   - `yValues` - array of vector with y-coordinates of the points.
-   - `zValues` - array of vector with z-coordinates of the points.
+   - `xValues` - array or vector with x-coordinates of the points.
+   - `yValues` - array or vector with y-coordinates of the points.
+   - `zValues` - array or vector with z-coordinates of the points.
    - `marker` - marker number (from 1 to 8), default: `1`.
    - `faceColor` - face (fill) color of the markers, default: `'transparent'`.
-   - `borderColor` - color markers' borders, default: `Colors.PRIMARY`.
+   - `borderColor` - color of the markers' borders, default: `Colors.PRIMARY`.
    - `borderWidth` - width (thickness) of the markers' borders in pixels, default: `1`.
    - `markerSize` - size of the markers in em, default: `1`.
-   - `title` - title of the line series group.
+   - `title` - title of the point series group, default: `''`.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import { Axes, Points } from 'svelte-plots-basic/3d';
 
@@ -46,8 +46,8 @@
 
    // reactive variables for coordinates of data points in pixels (and line style)
    const markerSymbol = $derived.by(() => {
-      if (typeof(marker) !== "number" || marker < 1 || marker > MARKER_SYMBOLS.length) {
-         console.error(`Points (3D): parameter 'marker' must be a number from 1 to ${MARKER_SYMBOLS.length}."`);
+      if (!Number.isInteger(marker) || marker < 1 || marker > MARKER_SYMBOLS.length) {
+         console.error(`Points (3D): parameter "marker" must be a whole number from 1 to ${MARKER_SYMBOLS.length}.`);
          return null;
       }
 
@@ -66,7 +66,6 @@
 
 <style>
    :global(.series-scatter > text) {
-      font-size: 1em;
       cursor: default;
    }
 

package/src/3d/Segments.svelte

@@ -11,24 +11,22 @@
    - `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`.
-   - `className` - CSS class name of the SVG group, default: `'series-seg'`.
    - `title` - title of the segment series group.
-   - `onclick` - function (callback) to be called when user clicks on any segment.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import { Axes, Segments } from 'svelte-plots-basic/3d';
 
-      const xStart = [1, 2, 3, 4];
-      const xEnd = [1, 2, 3, 4];
+      const xStart = [1, 2, 3, 4, 5];
+      const xEnd = [1, 2, 3, 4, 5];
       const yStart = [-2, -1, 0, -1, -2];
       const yEnd = [2, 1, 0, 1, 2];
-      const zStart = [1, 2, 3, 4];
-      const zEnd = [1, 2, 3, 4];
+      const zStart = [1, 2, 3, 4, 5];
+      const zEnd = [1, 2, 3, 4, 5];
    </script>
 
-   <Axes limX={[0, 5]} limY={[-3, 3]} >
+   <Axes limX={[0, 6]} limY={[-3, 3]} limZ={[0, 6]}>
       <Segments {xStart} {yStart} {zStart} {xEnd} {yEnd} {zEnd} lineColor="red" lineType={3} />
    </Axes>
    ```
@@ -37,7 +35,7 @@
    import { cbind } from 'mdatools/arrays';
    import { getContext } from 'svelte';
    import { Colors, LINE_STYLES } from '../constants';
-   import { checkCoords, transform3D } from '../methods';
+   import { checkCoords, transform3D, normalizeLineType } from '../methods';
 
 
    let {
@@ -62,6 +60,7 @@
    const ux2 = $derived(uz1 ? checkCoords(xEnd, 'Segments (3D)', ux1.length) : null);
    const uy2 = $derived(ux2 ? checkCoords(yEnd, 'Segments (3D)', ux1.length) : null);
    const uz2 = $derived(uy2 ? checkCoords(zEnd, 'Segments (3D)', ux1.length) : null);
+   const validLineType = $derived(normalizeLineType(lineType, 'Segments (3D)'));
 
    // combine world coordinates to matrices
    const uW1 = $derived(ux1 && uy1 && uz1 ? cbind(ux1, uy1, uz1) : null);
@@ -72,14 +71,13 @@
    const s1 = $derived(uW1 ? transform3D(uW1, axes.tM()) : null);
    const s2 = $derived(uW2 ? transform3D(uW2, axes.tM()) : null);
 
-   const lineStyleStr = $derived(`stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scale()][lineType-1]}`);
+   const lineStyleStr = $derived(`stroke:${lineColor};stroke-width: ${lineWidth}px;stroke-dasharray:${LINE_STYLES[axes.scale()][validLineType - 1]}`);
 </script>
 
-<g class="series series-segments" data-title={title} style={lineStyleStr}>
 {#if s1 && s2}
+<g class="series series-segments" data-title={title} style={lineStyleStr}>
    {#each s1.x as v, i}
       <line x1={s1.x[i]} x2={s2.x[i]} y1={s1.y[i]} y2={s2.y[i]} />
    {/each}
-{/if}
 </g>
-
+{/if}

package/src/3d/TextLabels.svelte

@@ -2,18 +2,22 @@
 @component Adds a series of text labels at given coordinates.
 
    Main properties:
-   - `xValues` - array of vector with x-coordinates of the points.
-   - `yValues` - array of vector with y-coordinates of the points.
-   - `zValues` - array of vector with z-coordinates of the points.
-   - `labels` - array with labels.
-   - `faceColor` - face (fill) color of the markers, default: `'transparent'`.
-   - `borderColor` - color markers' borders, default: `Colors.PRIMARY`.
-   - `borderWidth` - width (thickness) of the markers' borders in pixels, default: `1`.
-   - `textSize` - size of the markers in em, default: `1`.
-   - `title` - title of the line series group.
+   - `xValues` - array or vector with x-coordinates of the labels.
+   - `yValues` - array or vector with y-coordinates of the labels.
+   - `zValues` - array or vector with z-coordinates of the labels.
+   - `labels` - single string used at every coordinate or array with one string per coordinate.
+   - `faceColor` - text fill color, default: `Colors.PRIMARY_TEXT`.
+   - `borderColor` - text outline color, default: `'transparent'`.
+   - `borderWidth` - text outline width in pixels, default: `0`.
+   - `textSize` - text size in em, default: `1`.
+   - `fontWeight` - CSS font weight, default: `'normal'`.
+   - `className` - CSS class name for the labels group, default: `'series-textlabel'`.
+   - `title` - title of the labels group, default: `''`.
+
+   Values in `labels` are rendered as raw SVG/HTML markup. Only pass trusted content.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import { Axes, TextLabels } from 'svelte-plots-basic/3d';
 
@@ -56,10 +60,19 @@
 
    const l = $derived.by(() => {
       if (!ux) return null;
-      if(Array.isArray(labels) && labels.length !== ux.length ) {
-         console.error('TextLabels: labels provided as an array should have the same number of elements as number of coordinates.');
+
+      if (typeof labels === 'string') return labels;
+
+      if (!Array.isArray(labels)) {
+         console.error('TextLabels (3D): parameter "labels" must be a string or an array.');
          return null;
       }
+
+      if (labels.length !== ux.length) {
+         console.error('TextLabels (3D): labels provided as an array must have the same number of elements as coordinates.');
+         return null;
+      }
+
       return labels;
    });
 
@@ -75,7 +88,7 @@
 {#if s}
 <g class="series {className}" title={title} style={textStyleStr} >
 
-   {#if typeof labels === 'string'}
+   {#if typeof l === 'string'}
    {#each s.x as v, i}
       <text data-id={i} x={s.x[i]} y={s.y[i]} dx={0} dy={0}>{@html l}</text>
    {/each}
@@ -91,4 +104,4 @@
    text, text > :global(tspan) {
       dominant-baseline: middle;
    }
-</style>
+</style>

package/src/3d/XAxis.svelte

@@ -11,12 +11,11 @@
    - `textColor` - color of axis text labels, default: `Colors.DARKGRAY`.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import {Axes, XAxis} from 'svelte-plots-basic/3d';
    </script>
    <Axes>
-      // all other plotting components are here
       <XAxis label="X" showGrid={true} />
    </Axes>
    ```
@@ -36,7 +35,7 @@
    } = $props();
 
 
-   // get axes context and adjust x margins
+   // get axes context and synchronize x-axis settings
    const axes = getContext('axes');
    $effect(() => {
       axes.setXAxis({show: true, ticks, tickLabels, showGrid, label, lineColor, gridColor, textColor});
@@ -46,4 +45,3 @@
       axes.setXAxis({show: false});
    });
 </script>
-

package/src/3d/YAxis.svelte

@@ -3,20 +3,19 @@
 
    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`).
+   - `showGrid` - logical, show or hide grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limY`).
    - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
    - `lineColor` - color of axis line, default: `Colors.DARKGRAY`.
    - `gridColor` - color of axis grid line, default: `Colors.MIDDLEGRAY`.
    - `textColor` - color of axis text labels, default: `Colors.DARKGRAY`.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import {Axes, YAxis} from 'svelte-plots-basic/3d';
    </script>
    <Axes>
-      // all other plotting components are here
       <YAxis label="Y" showGrid={true} />
    </Axes>
    ```
@@ -36,7 +35,7 @@
    } = $props();
 
 
-   // get axes context and adjust x margins
+   // get axes context and synchronize y-axis settings
    const axes = getContext('axes');
    $effect(() => {
       axes.setYAxis({show: true, ticks, tickLabels, showGrid, label, lineColor, gridColor, textColor});
@@ -46,4 +45,3 @@
       axes.setYAxis({show: false});
    });
 </script>
-

package/src/3d/ZAxis.svelte

@@ -3,20 +3,19 @@
 
    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`).
+   - `showGrid` - logical, show or hide grid lines, default: `false`.
+   - `ticks` - array or vector with tick positions (by default will be generated automatically based on `limZ`).
    - `tickLabels` - array with tick labels to show at each tick (by default will be generated automatically).
    - `lineColor` - color of axis line, default: `Colors.DARKGRAY`.
    - `gridColor` - color of axis grid line, default: `Colors.MIDDLEGRAY`.
    - `textColor` - color of axis text labels, default: `Colors.DARKGRAY`.
 
    Example:
-   ```jsx
+   ```svelte
    <script>
       import {Axes, ZAxis} from 'svelte-plots-basic/3d';
    </script>
    <Axes>
-      // all other plotting components are here
       <ZAxis label="Z" showGrid={true} />
    </Axes>
    ```
@@ -36,7 +35,7 @@
    } = $props();
 
 
-   // get axes context and adjust x margins
+   // get axes context and synchronize z-axis settings
    const axes = getContext('axes');
    $effect(() => {
       axes.setZAxis({show: true, ticks, tickLabels, showGrid, label, lineColor, gridColor, textColor});
@@ -46,4 +45,3 @@
       axes.setZAxis({show: false});
    });
 </script>
-