svelte-plots-basic 3.3.0 → 4.0.0

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,18 +11,17 @@
    - `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>
    ```
 -->
 <script>
-   import { getContext } from 'svelte';
+   import { getContext, onDestroy } from 'svelte';
    import { Colors } from '../constants';
 
    let {
@@ -36,11 +35,13 @@
    } = $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});
    });
-</script>
-
 
+   onDestroy(() => {
+      axes.setXAxis({show: false});
+   });
+</script>

package/src/3d/YAxis.svelte

@@ -3,26 +3,25 @@
 
    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>
    ```
 -->
 <script>
-   import { getContext } from 'svelte';
+   import { getContext, onDestroy } from 'svelte';
    import { Colors } from '../constants';
 
    let {
@@ -36,11 +35,13 @@
    } = $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});
    });
-</script>
-
 
+   onDestroy(() => {
+      axes.setYAxis({show: false});
+   });
+</script>

package/src/3d/ZAxis.svelte

@@ -3,26 +3,25 @@
 
    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>
    ```
 -->
 <script>
-   import { getContext } from 'svelte';
+   import { getContext, onDestroy } from 'svelte';
    import { Colors } from '../constants';
 
    let {
@@ -36,11 +35,13 @@
    } = $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});
    });
-</script>
-
 
+   onDestroy(() => {
+      axes.setZAxis({show: false});
+   });
+</script>