@popovandrii/ui-elements/README.md

UI elements. Color scheme. Elements with complex logic Java Script. SpinBox, Select+search, Switch, Button Group (radio)

# UI elements

TypeScript-based NPM plugin.
The plugin includes interface elements with specific properties. 
UI elements that contain a large share of JavaScript.

## add JS
```js
import { SpinBox, Switch, Select, ButtonGroup } from '@popovandrii/ui-elements';
```
Connection with `standard styles` from the package by element name.
```js
new SpinBox(); 
new Switch();
new Select();
new ButtonGroup();
```
Connection with `custom styles` from a package by element name.
```js
new SpinBox({
  main: "You-costom-class",
  btn: "You-costom-class__btn",
  input: "You-costom-class__input",
  disabledBtn: "You-costom-class__disabled",
});

new Switch({ 
  main: "You-costom-class", 
  label: "You-costom-class-label" 
});

new Select({
  idPrefix: "UI-option-",
  main: "UIselect",
  selected: "UIselect-selected",
  arrow: "UIselect-arrow",
  optionsList: "UIselect-options",
  search: "UIselect-options__search",
  items: "UIselect-options__items",
  excludedItems: ["divider", "test"], // class="costom"
});

new ButtonGroup({ 
  main: "UIbg", 
  btn: "UIbg-btn", 
  input: "UIbg-input" 
  });
```

## Example for NodeJS + Express (index.umd.js + style.css)
```sh
npm install @popovandrii/ui-elements@latest
```
```js
// app.js 
app.use(
  '/ui-elements/css',
  express.static(path.join(__dirname, 'node_modules/bootstrap/dist/css'))
);
app.use(
  '/ui-elements/js',
  express.static(path.join(__dirname, 'node_modules/@popovandrii/ui-elements/dist'))
);
```
```html
<!-- you template ...ejs   -->
</head>
  <script src="/ui-elements/js/index.umd.js"></script>
  <link rel='stylesheet' href="/ui-elements/js/style.css" />
</head>

<!-- usually connected with a separate template -->
<div class="UIsp" data-step="<%= step %>" data-min="<%= min %>" data-max="<%= max %>" role="spinbutton" tabindex="0"
  aria-label="Numeric input">
  <div class="UIsp-label"><%= label %></div>
  <button class="UIsp__btn" type="button" aria-label="Decrease value">svg icon</button>
  <input class="UIsp__input" id="<%= id %>" type="text" value="<%= min %>" aria-hidden="true" inputmode="decimal">
  <button class="UIsp__btn" type="button" aria-label="Increase value">svg icon</button>
</div>

<script>
  // the constructor can contain an object with your custom style
  new UiElements.SpinBox();
  new UiElements.Switch();
  new UiElements.Select();;
</script>
```

## add Style
```js
import '@popovandrii/ui-elements/style.css';
```
*** You can not include styles from the package. Use your own styles.

Abbreviation of the base (main) class of each element:<br>
`UIsp`, UIdd, UIsw ...  (`UI + Spin-Box`, UI + Drop-Down, UI + Switch ...)<br>
`<div class="UIsp">...</div>`

### UI Elements

#### [Button group (radio)](/docs/button-group-radio/README.md)


#### Spin-Box
 This is a field with two buttons.<br> 
- the ability to set the minimum and maximum value
- the number of digits after the decimal point
- accelerated increment when holding down the `Shift` key
- setting the value directly in the field and increment using `arrows`
- value validation
- accessibility in accordance with the `A11Y` standard
- colors (danger primary...) and markup (sm lg radius-none)
- setting a custom CSS selector

```html
  <div class="UIsp lg r-0" data-step="4" data-min="1" data-max="5" role="spinbutton" tabindex="0"
    aria-label="Numeric input">
    <button class="UIsp__btn" type="button" aria-label="Decrease value">
      <svg width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">
        <path d="M1 7h14v2H1" />
      </svg>
    </button>
    <input class="UIsp__input" id="spin5-1" type="text" value="" aria-label="Current value" inputmode="decimal">
    <button class="UIsp__btn" type="button" aria-label="Increase value">
      <svg width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">
        <path d="M9 1v6h6v2H9v6H7V9H1V7h6V1" />
      </svg>
    </button>
  </div>
```
Important field <br>
`data-step="0"` - number of digits after the decimal point  (0 = 0; 3 = 0.000; 5 = 0.00100) <br>
`data-min="10"` - minimum value <br>
`data-max="15"` - maximum value <br>
The `<div class="UIsp-label">min 10 max 15 step 0</div>` field can be omitted.<br>
Additional styles <br>
size: lg sm `class="UIsp lg"`<br>
colors: `danger` `info` `success` `primary` `warning`<br>
radius: `r-0` `r-1`<br>

<p align="center">
<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/spinBox-UI.png" alt="SpinBox Preview" width="700">
</p>

#### Switch UI

```html
  <div class="UIsw" role="switch" tabindex="0">
    <label class="UIsw-label" for="ch0" id="label-ch0">Label</label>
    <input type="checkbox" id="ch0" name="btn3" checked hidden>
    <span class="UIsw-slider"></span>
    <span class="UIsw-slider__on">on</span>
    <span class="UIsw-slider__off">off</span>
  </div>
```
One of the `input` fields must be set to `checked` `hidden`<br>
The `<div class="UIsw-label">Status:</div>` <br>`<span class="UIsw-slider__on">on</span>` <br>`<span class="UIsw-slider__off">off</span>` field can be omitted.<br>
`aria-label` will be installed automatically.

Additional styles <br>
size: `lg` `sm`<br>
colors: `danger` `info` `success` `primary` `warning`<br>
radius: `r-0` `r-1`<br>

<p align="center">
<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/switch-UI.png" alt="Switch Preview" width="700">
</p>

#### Select UI
```html
  <div class="UIselect" id="mySelect2" tabindex="0" role="listbox" aria-haspopup="listbox">
    <span class="UIselect-selected">Select an option</span>
    <input type="hidden" name="myId2">
    <ul class="UIselect-options" hidden>
      <li class="UIselect-options__search" role="search">
        <input type="text" value="" aria-label="Search options">
      </li>
      <li class="UIselect-options__items" aria-hidden="true">
        <ul role="group">
          <li role="option" data-value="1">Option 1</li>
          <li role="option" data-value="2">Option 2</li>
          <li role="option" data-value="3">Option 3</li>
          <li role="presentation" class="divider" aria-hidden="true"></li>
          <li role="option" data-value="4">Option 4</li>
          <li role="option" data-value="5">Option 5</li>
          <li role="option" data-value="6">Option 6</li>
          <li role="option" data-value="7">Option 7</li>
          <li role="option" data-value="8">Option 8</li>
          <li role="option" data-value="9">Option 9</li>
          <li role="option" data-value="10">Option 10</li>
        </ul>
      </li>
    </ul>
  </div>
```

##### Search
```UIselect-options__search``` may be excluded
##### Send to server
```js
const select = document.getElementById('mySelect');
select?.addEventListener('change', (e) => {
  const value = e.detail?.value;
  console.log('Value:', value);
});
```

<p align="center">
<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/select-UI.png" alt="Switch Preview" width="700">
</p>


# Information for Developers
```sh
git clone git@gitlab.com:AndreyPopov/ui-elements.git && cd ui-elements
```

```sh
docker compose up -d --build
```

```sh
docker compose exec vite-dev sh
```

```sh
$ npm install
$ npm run build # Compile the project into the ./dist folder.
$ npm run dev # Work on the project 
$ npm run test # Vtest
$ npm run lint  
$ npm run format
$ npm install # before publishing the package (generation of the package-lock.json file)
$ npm login
$ npm publish --access public
$ npm info @popovandrii/ui-elements@0.0.x
$ npm install @popovandrii/ui-elements@latest
```

The `./playground` folder for viewing in a browser