DSI Units JS Library

DSI Units JS Library is a JavaScript library for parsing, rendering, and interactively editing D‑SI unit strings. This library is a port of the corresponding dsiunits Python package.

For details about the Digital Systems of Units (D-SI), please refer to https://doi.org/10.5281/zenodo.3816686.

The library includes two main components:

• DsiUnit – a class for parsing and rendering D‑SI unit strings.
• DsiUnitInput – a custom web component (<dsi-unit-input>) that provides an auto‑complete interactive input field for D‑SI units.

License

This project is licensed under the MIT License.

Installation

You can install this library with npm:

npm install -S dsiunits-js

Or clone the repository and bundle the code with your preferred bundler (Webpack, Rollup, etc.).

Usage

Importing the Library

For ES modules, import the classes as follows:

import { DsiUnit } from "dsiunits-js/src/dsiUnit.ts";
import "dsiunits-js/src/dsiUnitInput.ts"; // This registers the <dsi-unit-input> custom element.

Using the DsiUnit Class

The DsiUnit class is used to parse and render a D‑SI unit string.

Constructor

const unit = new DSIUnit("\\metre\\tothe{2}");

• Parameters:
  • dsiString (string): The raw D‑SI unit string (e.g., "\metre\tothe{2}").

Properties

• dsiString – The original D‑SI string.
• tree – The parsed representation of the D‑SI unit.
• warnings – An array of warnings encountered during parsing.
• nonDsiUnit – A boolean indicating whether the string was marked as a non‑DSI unit.
• valid – A boolean indicating whether the parsed unit is valid.
• scaleFactor – The overall scale factor (default: 1.0).

Methods

• toHTML(options)

  Renders the unit as an HTML string.

  Parameters:

  • options (object, optional):
    • wrapper (string): String to wrap the rendered output.
    • prefix (string): String to prepend.
    • suffix (string): String to append.
    • oneLine (boolean): If true, renders a compact, single‑line version (fractions with “/” and roots in inline format).

  Example:

  console.log(unit.toHTML({ oneLine: true }));

• toString()

  Returns the canonical D‑SI string representation.

  console.log(unit.toString());

Using the DsiUnitInput Web Component

The DsiUnitInput custom element provides an interactive auto‑complete input for D‑SI unit strings.

HTML Usage

<dsi-unit-input suggestions-list="kilo,mega,milli,metre,second,per,tothe"></dsi-unit-input>

Features

• Auto‑Completion:
  As you type after a backslash (\\), suggestions are provided based on context:

  • If a prefix is accepted (e.g., \milli), only allowed units are suggested.
  • If a unit is accepted, all allowed tokens (including \per and \tothe) are suggested.
  • Arrow keys navigate suggestions; Tab, Enter, or Right Arrow accept a suggestion.

• Focus/Blur Behavior:
  When the field loses focus, the rendered unit (using DsiUnit.toHTML({ oneLine: true })) is shown. Clicking the rendered output restores the raw input for editing.

• Customization:
  Override the allowed tokens by setting the suggestions-list attribute with a comma‑separated list.

Properties

• value
  Returns the current raw D‑SI unit string.

• live
  A boolean property (default: true) to enable/disable live updating.