Skip to content
Snippets Groups Projects
Commit 228a1410 authored by Benedikt's avatar Benedikt
Browse files

added reme for js libary

parent eb779a80
Branches
Tags
No related merge requests found
Pipeline #51769 failed
# 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 mainly LMM-generated version of the corresponding [dsiunits](https://pypi.org/project/dsiunits/) Python package. (Repository: [digitaldynamicmeasurement/dsiUnits](https://gitlab1.ptb.de/digitaldynamicmeasurement/dsiUnits)).
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 [LGPL-2.1](../LICENSE) License.
## Installation
You will be able to install the library via npm in near future:
```bash
npm install dsi-units-js-lib
```
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:
```js
import { DSIUnit } from "dsi-units-js-lib/src/dsiUnit.js";
import "dsi-units-js-lib/src/dsiUnitInput.js"; // 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
```js
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:**
```js
console.log(unit.toHTML({ oneLine: true }));
```
- **toString()**
Returns the canonical D‑SI string representation.
```js
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
```html
<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.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment