@popovandrii/ui-elements 0.1.3 → 0.2.0

package/README.md

@@ -1,33 +1,143 @@
-# UI elements
-Version 0.0.31
+# @popovandrii/ui-elements
 
-TypeScript-based NPM plugin.
-The plugin includes interface elements with specific properties. 
-UI elements that contain a large share of JavaScript.
+Lightweight TypeScript UI component library — **SpinBox**, **Select** (with search),
+**Switch**, **ButtonGroup** (radio), **Button**.
 
-## add JS
-```js
-import { SpinBox, Switch, Select, ButtonGroup } from '@popovandrii/ui-elements';
+- Zero runtime dependencies
+- Vanilla TypeScript — works with any framework or none
+- Accessible (ARIA / A11Y) with full keyboard support
+- Themeable via CSS custom properties — 4 built-in themes
+- SPA-friendly lifecycle: idempotent `scan()`, optional root scoping and `MutationObserver` auto re-scan, teardown-only `destroy()`
+- Custom DOM events + programmatic `setValue`
+- Ripple and flash animations (opt-out per element)
+- Ships as ES, CJS and UMD bundles with type declarations
+
+## Components
+
+| Component | Base class | Event | Docs |
+|---|---|---|---|
+| SpinBox | `UIsp` | `ui-spinbox-change` | [SpinBox](docs/spinBox/README.md) |
+| Select | `UIselect` | `ui-select-change` | [Select](docs/select/README.md) |
+| Switch | `UIsw` | `ui-switch-change` | [Switch](docs/switch/README.md) |
+| ButtonGroup | `UIbg` | `ui-button-group-change` | [ButtonGroup (radio)](docs/button-group-radio/README.md) |
+| Button | `UIb` | `ui-button-change` | [Button](docs/button/README.md) |
+
+## Installation
+
+```sh
+npm install @popovandrii/ui-elements@latest
 ```
-Connection with `standard styles` from the package by element name.
+
+## Quick start
+
+Import the components you need and the base stylesheet:
+
 ```js
-new SpinBox(); 
-new Switch();
+import { SpinBox, Select, Switch, ButtonGroup, Button } from "@popovandrii/ui-elements";
+import "@popovandrii/ui-elements/style.css";
+
+// Each constructor scans the DOM for its base class and wires up matching elements.
+new SpinBox();
 new Select();
+new Switch();
+new ButtonGroup();
+new Button();
+```
+
+Add the matching markup (see each component's docs for full examples):
+
+```html
+<div class="UIsp" data-step="0" data-min="0" data-max="10" role="spinbutton" tabindex="0" aria-label="Numeric input">
+  <button class="UIsp__btn" type="button" aria-label="Decrease value">−</button>
+  <input class="UIsp__input" id="qty" type="text" value="0" inputmode="decimal">
+  <button class="UIsp__btn" type="button" aria-label="Increase value">+</button>
+</div>
+```
+
+### Debug mode
+
+Pass `true` as the second constructor argument to log selector/value warnings:
+
+```js
 new ButtonGroup({}, true); // debug mode
 ```
-Connection with `custom styles` from a package by element name.
+
+## Themes
+
+Theming has two layers:
+
+- **`style.css`** — required. Contains the component structure **and the default `light`
+  palette at `:root`**, so the components render correctly with just this file and no
+  `data-theme` set.
+- **`theme-*.css`** — optional. Each provides one palette scoped under a higher-specificity
+  `html[data-theme="..."]` selector, so it overrides the `:root` default whenever the matching
+  `data-theme` is set — regardless of CSS import order.
+
+Zero-config (light theme, no `data-theme` needed):
+
+```js
+import "@popovandrii/ui-elements/style.css"; // that's it — light theme works
+```
+
+Add theme files only when you need other palettes or runtime switching:
+
 ```js
-new SpinBox({
-  main: "You-costom-class",
-  btn: "You-costom-class__btn",
-  input: "You-costom-class__input",
-  disabledBtn: "You-costom-class__disabled",
-});
+import "@popovandrii/ui-elements/style.css"; // required base (also = light default)
+
+// import "@popovandrii/ui-elements/theme-dark.css";
+// import "@popovandrii/ui-elements/theme-light-neon.css";
+// import "@popovandrii/ui-elements/theme-dark-neon.css";
+// import "@popovandrii/ui-elements/theme-light.css"; // only to switch *back* to light
+```
 
-new Switch({ 
-  main: "You-costom-class", 
-  label: "You-costom-class-label" 
+### Activate a theme with `data-theme`
+
+`light` is the implicit default. To use another theme, load its file and set `data-theme` on a
+parent — usually `<html>`:
+
+```html
+<html data-theme="dark">
+```
+
+Because themes are `html[data-theme="..."]` (higher specificity than `:root`), the explicit
+theme always wins over the default; remove the attribute to fall back to `light`.
+
+The `data-theme` values are: `light`, `dark`, `light-neon`, `dark-neon`.
+
+### Switching themes at runtime
+
+Because each theme is scoped by its selector, you can import several and switch between them
+by changing a single attribute:
+
+```js
+document.documentElement.dataset.theme = "dark"; // light | dark | light-neon | dark-neon
+```
+
+Themes are driven by CSS custom properties, so you can also override individual variables
+in your own stylesheet instead of shipping a full theme.
+
+### Shared CSS modifier classes
+
+Most components share a common set of modifier classes (see each component's docs for the
+exact list it supports):
+
+- **Color:** `primary`, `danger`, `info`, `success`, `warning`
+- **Size:** `sm`, `lg` (Switch also has `xsm`)
+- **Border radius:** `r-0`, `r-1` / `r-round`
+- **Gap:** `g-0`, `g-1`
+- **Layout:** `expand`, `between`, `around`, `vertical`, `border`
+
+## Custom class names
+
+Every component accepts a partial selector map to match your own markup classes. Defaults
+shown below:
+
+```js
+new SpinBox({
+  main: "UIsp",
+  btn: "UIsp__btn",
+  input: "UIsp__input",
+  disabledBtn: "disabled",
 });
 
 new Select({
@@ -38,135 +148,249 @@ new Select({
   optionsList: "UIselect-options",
   search: "UIselect-options__search",
   items: "UIselect-options__items",
-  excludedItems: ["divider", "test"], // class="costom"
+  flash: "UIselect--flash",
+  excludedItems: ["divider"], // <li> classes/ids excluded from selection
 });
 
-new ButtonGroup({ 
-  main: "UIbg", 
-  btn: "UIbg-btn", 
-  input: "UIbg-input" 
-  });
+new Switch({ main: "UIsw", label: "UIsw-label" });
+
+new ButtonGroup({ main: "UIbg", btn: "UIbg-btn", input: "UIbg-input" });
+
+new Button({ main: "UIb" });
 ```
 
-## Example for NodeJS + Express (index.umd.js + style.css)
-```sh
-npm install @popovandrii/ui-elements@latest
+## Events
+
+Each component dispatches a bubbling `CustomEvent` whose `detail` is `{ id, value }`:
+
+```js
+const el = document.getElementById("mySpinbox");
+el.addEventListener("ui-spinbox-change", (e) => {
+  console.log(e.detail); // { id: "mySpinbox", value: "3.1415" }
+});
 ```
+
+| Component | Event name | `detail.value` |
+|---|---|---|
+| SpinBox | `ui-spinbox-change` | current numeric value as string |
+| Select | `ui-select-change` | selected `data-value` |
+| Switch | `ui-switch-change` | `"true"` / `"false"` |
+| ButtonGroup | `ui-button-group-change` | selected `input[value]` |
+| Button | `ui-button-change` | element's `data-value` |
+
+### TypeScript typing
+
+```ts
+type UIChangeDetail = { id: string; value: string };
+
+document.addEventListener("ui-select-change", (e) => {
+  const { id, value } = (e as CustomEvent<UIChangeDetail>).detail;
+});
+```
+
+## Programmatic `setValue`
+
 ```js
-// app.js 
-app.use(
-  '/ui-elements/css',
-  express.static(path.join(__dirname, 'node_modules/bootstrap/dist/css'))
-);
+const sp = new SpinBox();
+sp.setValue(document.getElementById("mySpinbox"), 3.1415);
+
+const sl = new Select();
+sl.setValue(document.getElementById("mySelect"), "name"); // matches data-value
+
+const sw = new Switch();
+sw.setValue("idSwitchElement", true); // (inputId, boolean)
+
+const bg = new ButtonGroup();
+bg.setValue(document.getElementById("myGroup"), "btncheck2"); // matches input[value]
+
+const btn = new Button();
+btn.setValue(document.getElementById("myButton"), "/api/users/42", "Edit profile"); // value + optional label
+```
+
+## Lifecycle (SPA-friendly)
+
+Each instance attaches its listeners through a single `AbortController` created once in the
+constructor. The three building blocks:
+
+- **`scan()`** — binds every not-yet-bound element. It is **idempotent**: each control gets a
+  per-type marker (`data-uib-bound`, `data-uisel-bound`, `data-uisp-bound`, `data-uisw-bound`,
+  `data-uibg-bound`) and is skipped on later passes. Call it after rendering new markup — no
+  double-binding.
+- **`destroy()`** — teardown only: aborts all listeners, disconnects the observer, clears the
+  markers and recreates the `AbortController` so the **same instance can `scan()` again**. It
+  does **not** disable elements (behavior change — use `setDisabled()` on Button for that).
+- Markup-disabled elements (`data-disabled`, or `disabled` on the inner input) still render
+  disabled on every `scan()`.
+
+```js
+const sl = new Select();
+// ...after rendering new selects into the view:
+sl.scan();      // additive — existing listeners untouched, new ones bound
+// ...on final teardown:
+sl.destroy();   // listeners removed; elements left as-is
+```
+
+### Scope to a root
+
+Pass a third `options` argument to bind only inside a subtree. Useful when several managers of
+the same type live on one page (e.g. a parent view plus a child component):
+
+```js
+const widget = document.getElementById("cart-widget");
+const buttons = new Button({}, false, { root: widget }); // ignores .UIb outside the widget
+```
+
+### Auto re-scan with `observe`
+
+Add `observe: true` to attach a debounced `MutationObserver` on the root; new elements are
+bound automatically, so you can drop manual `scan()` calls:
+
+```js
+new Button({}, false, { root: appEl, observe: true });
+```
+
+### Singleton factory
+
+If you'd rather not hold your own single instance per type, use the lazy factories:
+
+```js
+import {
+  getButtonManager,
+  getSelectManager,
+  getSpinBoxManager,
+  getSwitchManager,
+  getButtonGroupManager,
+  resetManagers,
+} from "@popovandrii/ui-elements";
+
+getButtonManager({}, false, { observe: true }).scan(); // first call configures, then reused
+resetManagers();                                        // drop all cached singletons
+```
+
+The first call configures the manager (its arguments match the constructor); later calls
+return the same instance.
+
+## Animations
+
+- **Ripple** — radial wave on click
+- **Flash** — `box-shadow` glow when `setValue` is called
+
+Opt out per element or for any ancestor container:
+
+```html
+<div class="UIsp ui-no-ripple ui-no-flash">...</div>
+
+<!-- disable globally -->
+<body class="ui-no-ripple ui-no-flash">
+```
+
+## Usage without a bundler (NodeJS + Express, UMD)
+
+Serve the package's `dist` folder as static assets:
+
+```js
+// app.js
 app.use(
-  '/ui-elements/js',
-  express.static(path.join(__dirname, 'node_modules/@popovandrii/ui-elements/dist'))
+  "/ui-elements/js",
+  express.static(path.join(__dirname, "node_modules/@popovandrii/ui-elements/dist"))
 );
 ```
+
 ```html
-<!-- you template ...ejs   -->
-</head>
+<head>
+  <link rel="stylesheet" href="/ui-elements/js/style.css" />
+  <link rel="stylesheet" href="/ui-elements/js/theme-dark.css" />
+  <!-- <link rel="stylesheet" href="/ui-elements/js/theme-light.css" /> -->
+  <!-- <link rel="stylesheet" href="/ui-elements/js/theme-light-neon.css" /> -->
+  <!-- <link rel="stylesheet" href="/ui-elements/js/theme-dark-neon.css" /> -->
   <script src="/ui-elements/js/index.umd.js"></script>
-  <link rel='stylesheet' href="/ui-elements/js/style.css" />
-  <link rel='stylesheet' href="/ui-elements/js/theme-dark.css" />
-  <!-- <link rel='stylesheet' href="/ui-elements/js/theme-light.css" /> -->
-  <!-- <link rel='stylesheet' href="/ui-elements/js/theme-neon-dark.css" /> -->
-  <!-- <link rel='stylesheet' href="/ui-elements/js/theme-neon-light.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
+  // UMD exposes a global `UiElements`
   new UiElements.SpinBox();
   new UiElements.Switch();
-  new UiElements.Select();;
+  new UiElements.Select();
 </script>
 ```
 
-## add Style
-```js
-import '@popovandrii/ui-elements/style.css';
-// 4 design styles available.
-// theme-dark.css theme-neon-dark.css theme-neon-light.css
-import '@popovandrii/ui-elements/theme-light.css';
-```
-
-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>`
+## Documentation
 
-### UI Elements
+Each component has detailed docs covering markup, attributes, events, disabled states and
+examples:
 
+- [SpinBox](docs/spinBox/README.md) — numeric input with +/− buttons, min/max, decimal precision
+- [Select](docs/select/README.md) — dropdown with optional search and keyboard navigation
+- [Switch](docs/switch/README.md) — toggle based on `<input type="checkbox">`
+- [ButtonGroup (radio)](docs/button-group-radio/README.md) — radio group styled as buttons
+- [Button](docs/button/README.md) — styled button / link with event dispatch
 
-### Button group UI
 <p align="center">
-<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/button-group-UI.png" alt="Switch Preview" width="700">
+  <img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/button-group-UI.png" alt="ButtonGroup Preview" width="700">
 </p>
-
-#### [Button group README (radio)](/docs/button-group-radio/README.md)
-
-### Button UI
 <p align="center">
-<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/button-UI.png" alt="Switch Preview" width="700">
+  <img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/select-UI.png" alt="Select Preview" width="700">
 </p>
 
-#### [Button README (button)](/docs/button/README.md)
+## Development
 
-### Switch UI
-<p align="center">
-<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/switch-UI.png" alt="Switch Preview" width="700">
-</p>
+This project runs inside Docker (`node:24-alpine`); Node/npm are not required on the host.
 
-#### [Switch README (input)](/docs/switch/README.md)
+```sh
+git clone git@gitlab.com:AndreyPopov/ui-elements.git && cd ui-elements
 
-### SpinBox UI
-<p align="center">
-<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/spinBox-UI.png" alt="Switch Preview" width="700">
-</p>
+docker compose up -d --build      # start the dev container
+docker compose exec vite-dev sh   # shell into it
+```
 
-#### [SpinBox README (button -> input)](/docs/spinBox/README.md)
+Inside the container:
 
-#### Select UI
+```sh
+npm install
+npm run dev      # vite dev playground on port 5173
+npm run build    # build to ./dist (node build.js)
+npm run test     # vitest
+npm run lint     # eslint
+npm run format   # prettier
+```
 
-<p align="center">
-<img src="https://gitlab.com/AndreyPopov/ui-elements/-/raw/main/docs/images/select-UI.png" alt="Switch Preview" width="700">
-</p>
+The `./playground` folder hosts the browser demo and unit tests.
 
-#### [Select README](/docs/select/README.md)
+### Publishing
 
-# Information for Developers
 ```sh
-git clone git@gitlab.com:AndreyPopov/ui-elements.git && cd ui-elements
+npm install        # refresh package-lock.json
+npm login
+npm publish --access public
+npm info @popovandrii/ui-elements@latest
 ```
 
-```sh
-docker compose up -d --build
-```
+### Releasing
+
+`dist/` is git-ignored, so always build before packing or publishing. Tags use the
+`vX.Y.Z` scheme and point at the merge commit on `main`.
 
 ```sh
-docker compose exec vite-dev sh
+# 1. Bump the version on dev (no auto-tag — we tag on main after the merge)
+npm version 0.2.0 --no-git-tag-version
+git commit -am "Version: 0.2.0"
+
+# 2. Push dev and open a merge request dev -> main on GitLab, then merge it
+git push origin dev
+
+# 3. Tag the merged main (annotated) and push the tag
+git fetch origin
+git tag -a v0.2.0 origin/main -m "Release 0.2.0"
+git push origin v0.2.0
+
+# 4. Publish the build to npm (dist is git-ignored — build first)
+npm run build
+npm publish --access public
 ```
 
-```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
+On GitLab, create the release from **Deploy → Releases → New release**, pick the
+`vX.Y.Z` tag and paste the changelog as the release notes.
+
+## License
+
+[MIT](LICENSE) © Andrii Popov

package/dist/Button.d.ts

@@ -1,19 +1,31 @@
 interface SelectorMap {
     main: string;
 }
+interface InitOptions {
+    /** Limit scanning to this subtree instead of the whole document. */
+    root?: Document | HTMLElement;
+    /** Auto re-scan on DOM changes inside the root (debounced MutationObserver). */
+    observe?: boolean;
+}
 export declare class Button {
-    #private;
     private selectors;
     private buttons;
     private abortController;
     private dbug;
-    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean);
+    private root;
+    private observer;
+    private rescanTimer;
+    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean, options?: InitOptions);
+    /** Watch the root for added/removed nodes and re-scan (debounced). */
+    private observe;
     setValue(el: HTMLElement, value: string, label?: string): void;
     destroy(): void;
     private disableEl;
     private enableEl;
     private isDisabled;
     setDisabled(el: HTMLElement, disabled: boolean): void;
+    /** Bind every not-yet-bound `.UIb`. Safe to call repeatedly (SPA re-render). */
+    scan(): void;
     private ripple;
     private customEvent;
 }

package/dist/ButtonGroup.d.ts

@@ -3,16 +3,28 @@ interface SelectorMap {
     btn: string;
     input: string;
 }
+interface InitOptions {
+    /** Limit scanning to this subtree instead of the whole document. */
+    root?: Document | HTMLElement;
+    /** Auto re-scan on DOM changes inside the root (debounced MutationObserver). */
+    observe?: boolean;
+}
 export declare class ButtonGroup {
     #private;
     private selectors;
     private main;
     private abortController;
     private dbug;
-    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean);
+    private root;
+    private observer;
+    private rescanTimer;
+    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean, options?: InitOptions);
+    /** Watch the root for added/removed nodes and re-scan (debounced). */
+    private observe;
     destroy(): void;
-    private disableEl;
     setValue(el: HTMLElement, value: string): void;
+    /** Bind every not-yet-bound `.UIbg`. Safe to call repeatedly (SPA re-render). */
+    scan(): void;
     private costomEvent;
 }
 export {};

package/dist/Select.d.ts

@@ -9,14 +9,25 @@ interface SelectorMap {
     flash: string;
     excludedItems: Array<string>;
 }
+interface InitOptions {
+    /** Limit scanning to this subtree instead of the whole document. */
+    root?: Document | HTMLElement;
+    /** Auto re-scan on DOM changes inside the root (debounced MutationObserver). */
+    observe?: boolean;
+}
 export declare class Select {
     private selectors;
     private main;
     private itemArrowInitialized;
     private abortController;
     private dbug;
+    private root;
+    private observer;
+    private rescanTimer;
     private selectMap;
-    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean);
+    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean, options?: InitOptions);
+    /** Watch the root for added/removed nodes and re-scan (debounced). */
+    private observe;
     private filterExcluded;
     private filterSearch;
     destroy(): void;
@@ -28,7 +39,8 @@ export declare class Select {
      * @returns
      */
     setValue(el: HTMLElement, value: string | number): void;
-    private event;
+    /** Bind every not-yet-bound `.UIselect`. Safe to call repeatedly (SPA re-render). */
+    scan(): void;
     private itemArrow;
     private itemsPosition;
     private items;

package/dist/SpinBox.d.ts

@@ -4,18 +4,30 @@ interface SelectorMap {
     input: string;
     disabledBtn: string;
 }
+interface InitOptions {
+    /** Limit scanning to this subtree instead of the whole document. */
+    root?: Document | HTMLElement;
+    /** Auto re-scan on DOM changes inside the root (debounced MutationObserver). */
+    observe?: boolean;
+}
 export declare class SpinBox {
     private selectors;
     private spinBoxes;
     private abortController;
     private dbug;
-    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean);
+    private root;
+    private observer;
+    private rescanTimer;
+    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean, options?: InitOptions);
+    /** Watch the root for added/removed nodes and re-scan (debounced). */
+    private observe;
     private state;
     destroy(): void;
     private disableEl;
     setValue(el: HTMLElement, value: string | number): void;
     getValidDataNumber: (el: HTMLElement, attr: string) => number;
-    private event;
+    /** Bind every not-yet-bound `.UIsp`. Safe to call repeatedly (SPA re-render). */
+    scan(): void;
     private ripple;
     private costomEvent;
 }

package/dist/Switch.d.ts

@@ -2,15 +2,26 @@ interface SelectorMap {
     main: string;
     label: string;
 }
+interface InitOptions {
+    /** Limit scanning to this subtree instead of the whole document. */
+    root?: Document | HTMLElement;
+    /** Auto re-scan on DOM changes inside the root (debounced MutationObserver). */
+    observe?: boolean;
+}
 export declare class Switch {
     private selectors;
     private main;
     private abortController;
     private dbug;
-    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean);
+    private root;
+    private observer;
+    private rescanTimer;
+    constructor(selectors?: Partial<SelectorMap>, dbug?: boolean, options?: InitOptions);
+    /** Watch the root for added/removed nodes and re-scan (debounced). */
+    private observe;
     destroy(): void;
-    private disableEl;
-    private event;
+    /** Bind every not-yet-bound `.UIsw`. Safe to call repeatedly (SPA re-render). */
+    scan(): void;
     /**
      * Sets the state of a specific switch by its ID.
      * @param id ID of the internal input element