!logo web-ui-pack

Universal web package with high scalable WebComponents and helpers with focus on DX (developer experience)


Demo

You can see demo here or just clone repo and run npm i & npm start

Template repos with React: webpack-must-have, webpack-react (in progress)

Features

- Possible to use with any frameworks like Angular, React, Vue, etc. or even directly with HTML & JS (because it's js-native logic that doesn't require anything external)
- Form/controls are ready to use and have built-in validation logic for any case that you can imagine (see demo/controls)
- Focus on web-accessibility best practices (most popular packages have lower accessibility)
- High scalable and easily customizable (every component is developed for easy inheritance and redefine/extend default logic)
- Built-in CSS variables to use custom color themes with native ordinary styling (CSS, SCSS, etc.)
- Built-in dark color scheme. Add attribute wupdark () and define your colors for other content outside web-ui-pack
- Built-in Typescript (coverage types 100%)
- Built-in .jsx/.tsx support (for React/Preact)
- Supports different locales (based on localeInfo helper). For changing built-in messages override global function window.__wupln (details you can find in your editor during the coding via built-in intellisense)
- Well documented with JSDoc (use intellisense power of your editor to get details about each property/option/usage)
- Optimized for webpack (build includes only used components and helpers via side-effects option)
- Zero dependency (don't need to wait for bug-fixing of other packages)
- Always 100% test coverage via e2e and unit tests (it's a must-have and always will be so)
- Focus on performance (it's important to have low memory consumption and fast initialization)

Why the package is so big

It's developed with Typescript and has huge built-in documentation (JSDoc). Every method, property, event, and even local variables are documented well so you don't need extra resources to take an example to implement or configure elements. In the build result, without comments, you will see that it's small enough

Installing & usage

1. Install with npm npm install web-ui-pack
2. Add import { WUPPopupElement } from "web-ui-pack"; into any file (main.js for example)
3. Call WUPPopupElement.$use() to register the HTML tag into web-browser
4. For usage with React see CODESTYLE.md (for other frameworks it's very similar)
5. For usage with HTML + VSCode extend VSCode settings (For WebStorm it works out of the box - without extra config)

``json
// .vscode/settings.json
{
// ...
"html.customData": ["node_modules/web-ui-pack/types.html.json"]
}
`

6. Type & to see suggestions (if it doesn't work reload VSCode). More details below

TODO

- [x] Helpers
- _HTMLElement_ > _BaseElement_

- [x] DropdownElement demo
- [x] SpinElement demo
- [x] CircleElement demo
- _BaseModal_

- [x] PopupElement demo
- [ ] Tooltip Hook
- [x] ModalElement demo
- [x] Modal in modal
- [x] Confirm modal
- [x] Confirm hook (use WUPModal.$useConfirmHook)
- [x] Modal form
- [x] Notify demo

- [x] FormElement demo

- _BaseControl_

- [x] SwitchControl (toggler) demo
- [x] CheckControl (checkbox) demo
- [ ] CheckTreeControl
- [x] RadioControl (radioGroup) demo
- [x] Full customized
- [x] TextControl demo
- [x] Mask/pattern for controls demo
- [x] TextareaControl demo
- [ ] TextRichControl
- [x] PasswordControl demo
- [x] NumberControl demo
- [x] _BaseComboControl_
- [x] SelectControl (combobox) demo
- [ ] Full customized menu
- [x] SelectManyControl demo
- [ ] SearchControl
- [x] TimeControl demo
- [x] DateControl demo
- [x] option sync to sync with TimeControl
- [ ] option multiple
- [ ] DateTimeControl
- [ ] DateRangeControl
- [x] CalendarControl demo
- [ ] SliderControl (progress bar)
- [ ] FileControl
- [ ] ImageControl (AvatarEditor)
- [ ] ColorControl (ColorPicker)

- [ ] MediaPlayer (Video player)
- [ ] InfiniteScroll
- [ ] VirtualScroll
- [ ] CarouselElement (Slide show)
- [ ] TableElement

Components

Common rules:

1. Naming
- All components named WUP..Element, WUP..Control and have HTML-tags
- Public properties/options/events/methods startsWith $... (events $onOpen, $onClose, methods $open(), $close(), props like $isOpened etc.)
- Every component/class has static $defaults (common options for the current class) and personal $options (per each component). See details in example
- $options are observed. So changing options affects the component immediately after empty timeout (every component has static observedOptions as a set of watched options)
- all custom attributes update $options automatically. So document.querySelector('wup-spin').$options.inline equal to
2. Recommendations
- For webpack sideEffects switched on (for optimization). But if you don't use webpack don't import from web-ui-pack directly (due to tree-shaking can be not smart enough). Instead use web-ui-pack/path-to-element
- Every component has a good JSDoc so go ahead and read details directly during the coding
- Library compiled into ESNext. To avoid unexpected issues include this package into babel (use exclude: /node_modules\/(?!(web-ui-pack)\/).*/ for babel-loader)
3. Limitations
- In jsx/tsx instead of className use class attribute (React issue)
- If you change custom html-attributes it will update $options, but if you change some option it removes related attribute (for performance reasons). Better to avoid usage attributes at all
4. Inheritance
- Components are developed to be easily customized and inherited. Use ...$defaults of every class to configure behavior. You can rewrite everything you can imagine without digging a lot in a code. To be sure don't hesitate to take a look on \*.d.ts or source code (there are enough comments to clarify even weird/difficult cases)
- All Components inherited from WUPBaseElement that extends default HTMLElement
- All internal event-callbacks startsWith got... (gotReady, gotRemoved)
- To redefine the component just extend it and register with a new html tag OR redefine default behavior via prototype functions (if $defaults are not included something). See details in example

---

$3

More details you can find in CODESTYLE.md and FAQ

Typescript

`typescript
import WUPPopupElement, { PopupOpenCases } from "web-ui-pack/popup/popupElement";
import "web-ui-pack/popup/popupPlacements"; // just in case if TS doesn't auto-import tied namespace

WUPPopupElement.$use(); // call it to register in the system
// redefine some defaults; WARN: you can change placement rules here without changing $options per each element!!!
WUPPopupElement.$defaults.offset = [2, 2];
WUPPopupElement.$defaults.minWidthByTarget = true;
WUPPopupElement.$defaults.arrowEnable = true;

// create element
const el = document.createElement("wup-popup");
// WARN el.$options is a observable-clone of WUPPopupElement.$defaults
// WARN: PopupOpenCases is const enum and import PopupOpenCases available only in Typescript
el.$options.openCase = PopupOpenCases.onClick | PopupOpenCases.onFocus; // show popup by target.click and/or target.focus events
el.$options.target = document.querySelector("button");
/*
Placement can be $top, $right, $bottom, $left (top - above at the target etc.)
every placement has align options: $start, $middle, $end (left - to align at the start of target)
also, you can set $adjust to allow Reduce popup to fit layout
*/
el.$options.placement = [
WUPPopupElement.$placements.$top.$middle; // place at the top of target and align by vertical line
WUPPopupElement.$placements.$bottom.$middle.$adjust, // adjust means 'ignore align to fit layout
WUPPopupElement.$placements.$bottom.$middle.$adjust.$resizeHeight, // resize means 'allow to resize to fit layout'
]
document.body.append(el);
``

HTML, JSX, TSX

`html
Target

Some content here
`

How to extend/override

`typescript
/// popup.ts

// you can override via prototypes
const original = WUPPopupElement.prototype.goOpen;
WUPPopupElement.prototype.goOpen = function customGoShow() {
if (window.isBusy) {
return null;
}
return original(...arguments);
};

/ OR create extended class /

class Popup extends WUPPopupElement {
// take a look on definition of WUPPopupElement and you will find internals
protected override goOpen(openCase: PopupOpenCases): boolean {
if (openCase === PopupOpenCases.onHover) {
return false;
}
return super.goOpen(openCase);
}
}

const tagName = "ext-popup";
customElements.define(tagName, Popup);
// That's it. New Popup with custom tag 'ext-popup' is ready

// add for intellisense (for *.ts only)
declare global {
// add element to DOM document.createElement
interface HTMLElementTagNameMap {
[tagName]: Popup;
}
}

declare module "react" {
// add element for tsx/jsx intellisense
namespace JSX {
interface IntrinsicElements {
[tagName]: IntrinsicElements["wup-popup"]; // reuse same definition from wup-popup
}
}
}
`

---

$3

use import focusFirst from "web-ui-pack/helpers/focusFirst" etc.\
WARNING: avoid using import { focusFirst } from "web-ui-pack; because in this case the whole web-ui-pack module traps in compilation of dev-bundle and increases time of compilation

#### Helpers.Animation

- animateDropdown ⇒ Animate (show/hide) element as dropdown via scale and counter-scale for children
- animateStack ⇒ Animate (show/hide) every element via moving from target to own position

#### Helpers.HTML (DOM)

- findScrollParent ⇒ Find first parent with active scroll X/Y
- findScrollParentAll ⇒ Find all parents with active scroll X/Y
- focusFirst ⇒ Set focus on element or first possible nested element
- isIntoView ⇒ Check if element is visible in scrollable parents
- scrollIntoView ⇒ Scroll the HTMLElement's parent container such that the element is visible to the user and return promise by animation end
- class WUPScrolled ⇒ Class makes pointed element scrollable and implements carousel-scroll behavior (appends new items during the scrolling). Supports swipe/pageUp/pageDown/mouseWheel events.

#### Helpers.Date

- dateCompareWithoutTime ⇒ Compare by Date-values without Time
- dateCopyTime ⇒ Copy hh:mm:ss.fff part from B to A
- dateFromString ⇒ Returns parsed date from string based on pointed format
- dateToString ⇒ Returns a string representation of a date-time according to pointed format

#### Helpers.Math

- mathFixFP ⇒ Fix float precision issue after math operations when 10.53+0.1=>10.629999999999999
- mathScaleValue ⇒ Scale value from one range to another
- mathRotate ⇒ Apply transform.rotate on point

#### Helpers.Object

- nestedProperty.set ⇒ nestedProperty.set(obj, "value.nestedValue", 1) sets obj.value.nestedValue = 1
- nestedProperty.get ⇒ nestedProperty.get(obj, "nested.val2", out?: {hasProp?: boolean} ) returns value from obj.nested.val2
- objectClone ⇒ Deep cloning object
- objectToFormData ⇒ Converts pointed object with nested properties to FormData (including files)
- observer ⇒ Converts object to observable (via Proxy) to allow listen for changes

#### Helpers.Event

- onEvent ⇒ More strict (for Typescript) wrapper of addEventListener() that returns callback with removeListener()
- onFocusGot ⇒ Fires when element/children takes focus once (fires again after onFocusLost on element)
- onScroll ⇒ Handles wheel & touch events for custom scrolling
- onScrollStop ⇒ Returns callback when scrolling is stopped (via checking scroll position every frame-render)
- onFocusLost ⇒ Fires when element/children completely lost focus
- onSpy ⇒ Spy on method-call of object

#### Helpers.String

- stringLowerCount ⇒ Returns count of chars in lower case (for any language with ignoring numbers, symbols)
- stringUpperCount ⇒ Returns count of chars in upper case (for any language with ignoring numbers, symbols)
- stringPrettify ⇒ Changes camelCase/snake_case/kebab-case text to user-friendly title: 'somePropValue' to 'Some Prop Value'

#### Helpers.Other

- promiseWait ⇒ Produce Promise during for "no less than pointed time"; it helps for avoding spinner blinking during the very fast API-request in case: pending > waitResponse > resetPending
- localeInfo ⇒ Locale-object with definitions related to user-locale
- TimeObject ⇒ Plane time object without date

---

$3

Be sure that you are familiar with common rules

#### Library doesn't work in some browsers

> web-ui-pack is compiled to ESNext. So some features may not exist in browsers. To resolve it include the lib into babel-loader (for webpack check module.rules...exclude sections)
>
> `js
> // webpack.config.js
> {
> test: /\.(js|jsx)$/,
> exclude: (() => {
> // these packages must be included to change according to browserslist
> const include = ["web-ui-pack"];
> return (v) => v.includes("node_modules") && !include.some((lib) => v.includes(lib));
> })(),
> use: [ "babel-loader", ],
> },
> `

#### UI doesn't recognize HTML tags like etc

> It's possible that you missed import or it was removed by the optimizer of webpack etc. To fix this need to force import at least once and don't forget to call .$use()
>
> `js
> import { WUPSelectControl, WUPTextControl } from "web-ui-pack";
>
> WUPTextControl.$use(); // register element
> WUPSelectControl.$use(); // register element
> // etc.
> ``

$3

see demo/faq