svelte-plots-basic 3.4.0 → 4.0.0

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>
-

package/src/ExportDialog.svelte

@@ -9,6 +9,7 @@
    - `onclose` - callback when dialog is closed.
 -->
 <script>
+   import { onDestroy } from 'svelte';
    import { downloadPNG } from './methods.js';
 
    let {
@@ -19,24 +20,40 @@
       onclose
    } = $props();
 
-   // aspect ratio from the actual SVG element
-   const svgWidth = plotElement ? (plotElement.clientWidth || plotElement.getBoundingClientRect().width) : 1;
-   const svgHeight = plotElement ? (plotElement.clientHeight || plotElement.getBoundingClientRect().height) : 1;
-   const aspectRatio = svgWidth / svgHeight;
-
-   // editable state — height always derived from width to preserve aspect ratio
    const resOptions = [100, 150, 300, 600];
-   const parsedInitialRes = Number(initialRes);
-   const defaultRes = resOptions.includes(parsedInitialRes) ? parsedInitialRes : 300;
 
-   let width = $state(initialWidth);
+   // The dialog intentionally takes a snapshot of its initial props when it opens.
+   function getInitialValues() {
+      const svgWidth = plotElement ? (plotElement.clientWidth || plotElement.getBoundingClientRect().width) : 1;
+      const svgHeight = plotElement ? (plotElement.clientHeight || plotElement.getBoundingClientRect().height) : 1;
+      const parsedInitialRes = Number(initialRes);
+
+      return {
+         svgWidth,
+         svgHeight,
+         aspectRatio: svgWidth / svgHeight,
+         width: initialWidth,
+         res: resOptions.includes(parsedInitialRes) ? parsedInitialRes : 300,
+         name: typeof fileName === 'string' ? fileName : 'plot'
+      };
+   }
+
+   const initialValues = getInitialValues();
+   const svgWidth = initialValues.svgWidth;
+   const svgHeight = initialValues.svgHeight;
+   const aspectRatio = initialValues.aspectRatio;
+
+   // editable state — height always derived from width to preserve aspect ratio
+   let width = $state(initialValues.width);
    const height = $derived(Math.max(4, Math.min(20, Math.round(width / aspectRatio * 10) / 10)));
-   let res = $state(defaultRes);
-   let name = $state(fileName);
+   let res = $state(initialValues.res);
+   let name = $state(initialValues.name);
    const nameValid = $derived(name.trim().length > 0);
+   let exportError = $state('');
 
    // preview container ref
    let previewContainer = $state(null);
+   let dialogElement = $state(null);
 
    // max preview width in pixels
    const maxPreviewWidth = 400;
@@ -78,73 +95,206 @@
    }
 
    let saving = $state(false);
+   let activeExportCleanup = null;
+   let destroyed = false;
+
+   onDestroy(() => {
+      destroyed = true;
+      activeExportCleanup?.();
+      if (dialogElement?.open) dialogElement.close();
+   });
+
+   $effect(() => {
+      if (dialogElement && !dialogElement.open) {
+         dialogElement.showModal();
+         dialogElement.querySelector('#export-name')?.focus();
+      }
+   });
+
+   function closeDialog() {
+      if (dialogElement?.open) dialogElement.close();
+      onclose();
+   }
 
    function handleSave() {
       if (saving) return;
-      saving = true;
+
+      exportError = '';
+
+      const exportWidth = Number(width);
+      const exportHeight = Number(height);
+      const exportRes = Number(res);
+
+      const hasValidSize = Number.isFinite(exportWidth) && exportWidth >= 1 && exportWidth <= 30 &&
+         Number.isFinite(exportHeight) && exportHeight >= 1 && exportHeight <= 30;
+      const hasValidResolution = Number.isFinite(exportRes) && exportRes >= 50 && exportRes <= 1200;
+
+      if (!hasValidSize || !hasValidResolution) {
+         exportError = 'Export size or resolution is invalid.';
+         return;
+      }
+
+      if (!plotElement || !(plotElement instanceof SVGElement) || !plotElement.parentElement) {
+         exportError = 'The plot is not available for export.';
+         return;
+      }
 
       const container = plotElement.parentElement;
       const origStyle = container.style.cssText;
+      let observer = null;
+      let fallbackTimer = null;
+      let firstFrame = null;
+      let secondFrame = null;
+      let exportStarted = false;
+      let restored = false;
+
+      function restorePlot() {
+         if (restored) return;
+         restored = true;
+
+         observer?.disconnect();
+         if (fallbackTimer !== null) clearTimeout(fallbackTimer);
+         if (firstFrame !== null) cancelAnimationFrame(firstFrame);
+         if (secondFrame !== null) cancelAnimationFrame(secondFrame);
+
+         container.style.cssText = origStyle;
+         saving = false;
+
+         if (activeExportCleanup === restorePlot) {
+            activeExportCleanup = null;
+         }
+      }
+
+      function failExport(error) {
+         console.error('Failed to prepare the plot for PNG export.', error);
+         exportError = 'PNG export could not be started.';
+         restorePlot();
+      }
+
+      function finishExport() {
+         restorePlot();
+         if (!destroyed) closeDialog();
+      }
+
+      activeExportCleanup = restorePlot;
+      saving = true;
 
       // scale reference width with export width so smaller plots get
       // a smaller scale category → relatively larger fonts and details
       // 4cm → 360px (small), 8cm → 520px (medium), 16cm → 840px (large), 20cm → 1000px (xlarge)
-      const refWidth = Math.round(200 + width * 40);
+      const refWidth = Math.round(200 + exportWidth * 40);
       const refHeight = Math.round(refWidth / aspectRatio);
 
       function doExport() {
-         requestAnimationFrame(() => {
-            requestAnimationFrame(() => {
-               // onSerialize callback fires after downloadPNG has serialized the SVG,
-               // so we can safely restore the container and close the dialog
-               downloadPNG(plotElement, name.trim(), width, height, res, () => {
-                  container.style.cssText = origStyle;
-                  saving = false;
-                  onclose();
+         if (exportStarted || restored) return;
+         exportStarted = true;
+
+         observer?.disconnect();
+         if (fallbackTimer !== null) clearTimeout(fallbackTimer);
+
+         try {
+            firstFrame = requestAnimationFrame(() => {
+               firstFrame = null;
+               secondFrame = requestAnimationFrame(() => {
+                  secondFrame = null;
+
+                  try {
+                     // The callback fires after downloadPNG has serialized the SVG,
+                     // so the live container can be restored before image encoding finishes.
+                     const result = downloadPNG(
+                        plotElement,
+                        name.trim(),
+                        exportWidth,
+                        exportHeight,
+                        exportRes,
+                        finishExport
+                     );
+
+                     if (result === null) {
+                        failExport(new Error('downloadPNG rejected the export settings.'));
+                     }
+                  } catch (error) {
+                     failExport(error);
+                  }
                });
             });
-         });
+         } catch (error) {
+            failExport(error);
+         }
       }
 
-      // temporarily resize plot container to a fixed reference size (off-screen,
-      // hidden behind the dialog backdrop) so Svelte recomputes the layout
-      container.style.cssText = `position:fixed;left:-9999px;top:-9999px;width:${refWidth}px;height:${refHeight}px;overflow:hidden;`;
-
-      // wait for ResizeObserver → Svelte bindings → derived recomputation → DOM update
-      // fallback timeout in case container is already at the target size
-      const fallbackTimer = setTimeout(() => { observer.disconnect(); doExport(); }, 500);
-      const observer = new ResizeObserver(() => {
-         observer.disconnect();
-         clearTimeout(fallbackTimer);
-         doExport();
-      });
-      observer.observe(plotElement);
+      try {
+         // temporarily resize plot container to a fixed reference size (off-screen,
+         // hidden behind the dialog backdrop) so Svelte recomputes the layout
+         container.style.cssText = `position:fixed;left:-9999px;top:-9999px;width:${refWidth}px;height:${refHeight}px;overflow:hidden;`;
+
+         // wait for ResizeObserver → Svelte bindings → derived recomputation → DOM update
+         // fallback timeout in case container is already at the target size
+         fallbackTimer = setTimeout(doExport, 500);
+         observer = new ResizeObserver(doExport);
+         observer.observe(plotElement);
+      } catch (error) {
+         failExport(error);
+      }
    }
 
-   function handleBackdropClick() {
-      if (!saving) onclose();
+   function handleCancel(e) {
+      e.preventDefault();
+      if (!saving) closeDialog();
    }
 
    function handleDialogClick(e) {
       e.stopPropagation();
+      if (saving) return;
+
+      const bounds = e.currentTarget.getBoundingClientRect();
+      const clickedOutside = e.clientX < bounds.left || e.clientX > bounds.right ||
+         e.clientY < bounds.top || e.clientY > bounds.bottom;
+
+      if (clickedOutside) closeDialog();
    }
 
-   // close on Escape key
-   $effect(() => {
-      function handleKeydown(e) {
-         if (e.key === 'Escape' && !saving) {
-            onclose();
-         }
-      }
-      document.addEventListener('keydown', handleKeydown);
-      return () => document.removeEventListener('keydown', handleKeydown);
-   });
+   // Keep keyboard events from activating an enclosing custom modal's handlers.
+   // Native dialog behavior still handles Escape; the explicit Tab order avoids
+   // browser/OS differences in which form controls participate in navigation.
+   function handleKeydown(e) {
+      e.stopPropagation();
+
+      if (e.key !== 'Tab' || !dialogElement) return;
+
+      const resolutionInput = dialogElement.querySelector(
+         'input[name="export-res"]:checked'
+      ) ?? dialogElement.querySelector('input[name="export-res"]');
+
+      const controls = [
+         dialogElement.querySelector('#export-name'),
+         dialogElement.querySelector('#export-width'),
+         resolutionInput,
+         ...dialogElement.querySelectorAll('.export-dialog-actions button:not(:disabled)')
+      ].filter(Boolean);
+
+      if (controls.length === 0) return;
+
+      const currentIndex = controls.indexOf(document.activeElement);
+      const nextIndex = currentIndex === -1
+         ? (e.shiftKey ? controls.length - 1 : 0)
+         : (currentIndex + (e.shiftKey ? -1 : 1) + controls.length) % controls.length;
+
+      e.preventDefault();
+      controls[nextIndex].focus();
+   }
 </script>
 
-<!-- svelte-ignore a11y_click_events_have_key_events -->
-<!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="export-dialog-backdrop" onclick={handleBackdropClick}>
-   <div class="export-dialog" onclick={handleDialogClick}>
+<!-- Native modal events provide backdrop closing and isolate an enclosing custom modal's keyboard handlers. -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<dialog
+   class="export-dialog"
+   aria-label="Export as PNG"
+   bind:this={dialogElement}
+   oncancel={handleCancel}
+   onclick={handleDialogClick}
+   onkeydown={handleKeydown}
+>
       <div class="export-dialog-title">Export as PNG</div>
 
       <div class="export-dialog-body">
@@ -177,37 +327,34 @@
                   {/each}
                </div>
             </div>
+
+            {#if exportError}
+               <p class="export-dialog-error" role="alert">{exportError}</p>
+            {/if}
          </div>
       </div>
 
       <div class="export-dialog-actions">
-         <button type="button" class="export-dialog-cancel" onclick={onclose} disabled={saving}>Cancel</button>
-         <button type="button" class="export-dialog-save" onclick={handleSave} disabled={!nameValid}>Save</button>
+         <button type="button" class="export-dialog-cancel" onclick={closeDialog} disabled={saving}>Cancel</button>
+         <button type="button" class="export-dialog-save" onclick={handleSave} disabled={!nameValid || saving}>Save</button>
       </div>
-   </div>
-</div>
+</dialog>
 
 <style>
-   .export-dialog-backdrop {
-      position: fixed;
-      top: 0;
-      left: 0;
-      right: 0;
-      bottom: 0;
+   .export-dialog::backdrop {
       background: rgba(0, 0, 0, 0.4);
-      z-index: 1000;
-      display: flex;
-      align-items: center;
-      justify-content: center;
    }
 
    .export-dialog {
+      box-sizing: border-box;
       background: #fefefe;
+      border: none;
       border-radius: 0.5em;
       box-shadow: 0 4px 24px rgba(0, 0, 0, 0.25);
       padding: 1.25em;
       min-width: 440px;
       max-width: 90vw;
+      margin: auto;
       font-family: Arial, Helvetica, sans-serif;
       color: #606060;
    }
@@ -316,7 +463,30 @@
    }
 
    .export-dialog-res-btn input {
-      display: none;
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      clip-path: inset(50%);
+      white-space: nowrap;
+      border: 0;
+   }
+
+   .export-dialog-name:focus-visible,
+   .export-dialog-control input[type="range"]:focus-visible,
+   .export-dialog-actions button:focus-visible,
+   .export-dialog-res-btn:focus-within {
+      outline: 2px solid #999191;
+      outline-offset: 2px;
+   }
+
+   .export-dialog-error {
+      margin: 0;
+      color: crimson;
+      font-size: 0.85em;
    }
 
    .export-dialog-actions {