# ui-widgets [![](https://data.jsdelivr.com/v1/package/gh/sdxmessaging/ui-widgets/badge)](https://www.jsdelivr.com/package/gh/sdxmessaging/ui-widgets) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=sdxmessaging_ui-widgets&metric=alert_status&token=316dd863c9185ce988acd14efc1fdb66791b67ba)](https://sonarcloud.io/summary/new_code?id=sdxmessaging_ui-widgets)

Build powerful form inputs/outputs with mithril and streams.

[Open Example Page in Flems.io](https://flems.io/#0=N4IgzgpgNhDGAuEAmIBcIAW94AcyoHoDYkA7AOgCswloBLANwCdzSJ4CBzDAmgDwC2EMGACGnOqU4EArnQC0AdzpJO7MAQh9RAnDCpgQAGhCwA9qTBmYaU9aii8yY+FhN7aANoAGIwGY-ADYAXRMAMzoYQ1RPUFIdCFtyLAEoF3NSREzbAB4oSQBrAAImaABeAB1weABPKIwIdiqijFKwysxsPEJiMmpyWCgzGSQwh1KBswECUUpRPgJ8gCMNMIt4eVFFYSmIAkDyACZyb2IRGagocgFJAZFmyUROJjpajrAMUQBWAEZD+T4GECAHkCABhAoARTMAAVgQB1AAiSAAmgAVREARwgACUkDCwQA1JA-ADKOAYYIAggBOAAadNgAFVSAAtUmHABiAgAUgA5HA-cxUzkALwY8DBfJpACEBDoAKIAagALKIABIAaQAHDUakz1UzSWDYDz1Zw6UM0TU0YcqWUOkU3GYRGYXhJSB1RKQLDUBMMwM02hAmKUmDhrHRYDUOj75MHQyGqgQAHwVUg5JZmJA1J0OETvb1geSQF5hIphRSHCsqopIURMAryZ6iGpVFM5JCMIoqDo4cQQds5AhdhgdghZnMplyQGAIOgWaIgH6oADs3hAAF9QiB8qQCtFYiB4kJbLARAB+MI6SIxsGiBgQUTwFwyJhpdBYXD4IhrTJgchODMMxOBgRw6AA8xpnPMArxvKA7wfJ8XxMWocESdAwFqGxNyMOIElseBRFgDAakXa5bhg1931sL9uiIEhSH6QZhlGcYIEmaZZnmRY6BWAgiJIsjLAIFVyB+H5xIE4jSPIm4KCo1CanQ2wsLqRJcPw090DGZ8cCjAoWHku5DBMN8P06b8ekYgxaHyZhWHYAhSBwaZdNwAymAAATEg4fj8EcII4dz9NgQyKIUkQXDQjDqnUrc8OPAj0DkJQVDUeBIKisyaM-Lof16ChqDsxgWDYDhuF4JBBGEMQPWkVLlFUdQzg0Rr0vUEzouU2K1JwxKT1im54FaSIIoMaiLLogqZBcgpOE4ghhtGqAvOObxyBVJbXhW8bqG6lTMLcOgcBfTSku06pSh0Cacqm-KelmnB5sW5aXlW9bNt4eBrumLDftukAYtU47ToSrTYqGesPj20yQHM2iHoYvpIKGEZdImKCZjmBZlg0KHRBh6hRPE1cjh+RZs0JjBYYO3rQbOgbkt3GQ+AsWm7sRqzkaY1HWIxjise43G+Px1mLAIPxNpORZxYoYz9qUw7XBeMHzsG1S6E4eJ4DfCAAH1+yQcgZAEY2FbhhG8u5wrbPoBzyuc1zeC1nW9cN0QkB8k5yFXQKsJd7Xn3do2TbNjmgZ6kHVcZiHbBCzzvb8vxJq5+jbeK+2yqcly3IcDywu83zxJTpX6Zj8GLtiyRaD4QGrcs9ObMz+zs4qnh+CEERxEkBqFCajK2rNgga60QHgaOiv1eZrQdD0DjFfh3LG4K5uaCzxz26qmru-q2R+46zLNG0XR9EXieVZOs6dw1lKD+azKigVE-56KLcgA)

---

## Overview

ui-widgets is a simple collection of mithril components for generating rich form inputs or displaying values. These widgets use mithril streams to simplify avoid state management "boilerplate" and allow form complex interactions and validation.

---

## Installation

## 3rd Party Dependencies

ui-widgets has several lightweight dependencies for building and styling widgets:

* [mithril.js + streams](https://mithril.js.org/)
* [Lodash](https://lodash.com/)
* [Tachyons](https://tachyons.io/)
* [Luxon](https://moment.github.io/luxon/#/)
* We suggest using [Font Awesome](https://fontawesome.com/) for icons
* Signature drawing input requires [Signature Pad](https://github.com/szimek/signature_pad)
* Signature text/stamp input benefits from a custom font, we suggest [Caveat](https://fonts.googleapis.com/css?family=Caveat)

### Install with NPM

Register the GitHub Package Registry for @sdxmessaging in your .npmrc file:

```text
@sdxmessaging:registry=https://npm.pkg.github.com
```

Add @sdxmessaging/ui-widgets to your package:

```bash
npm i @sdxmessaging/ui-widgets
```

### From CDN

A umd version of the library is available via jsDelivr:

```html
<script crossorigin="anonymous" src="https://cdn.jsdelivr.net/gh/sdxmessaging/ui-widgets/umd/index.js"></script>
```

### Quick-start with example page

A simple demonstration page is available from ui-widgets, open the example.html file:

```bash
npm run example
```

The example page shows how widgets read/write shared streams and file streams. The page source can be found in the `umd` folder.

## Concepts

All widgets accept a "field" configuration and a "value" stream, the streams contain either a simple property or a file list. Any input/display widget that supports the same "value" can share a common stream.

### Properties

A property "value" consists of a stream of string, number, or boolean.

The SelectInput, RadioInput, and SelectText widgets require a list of options mapping the value to a label.

### Files

A file "value" consists of a stream of file objects. These objects are simple wrappers for standard browser files with extra fields:

* guid - Auto generated unique id
* name - The file name, may be modified by image inputs
* path - A path to the file, used by file display widgets
* dataUrl (optional) - Scaled image preview generated by image inputs