npm package: @scepi/node-red-dashboard-2-ui-package
Description: A collection of UI nodes/widgets
Author: Martin Dallos
Latest version: 1.1.5

# Scepi UI Widgets for Node-RED Dashboard 2.0

> Custom Vue-powered widgets for Node-RED Dashboard 2.0, tailored for residential Scepi deployments.

This package bundles production-ready Dashboard 2.0 widgets (runtime nodes + Vue components) that can be installed straight from the Node-RED palette or developed locally with Vite.

## Widget Catalogue

| Widget | Node-RED type | Highlights |
| ------ | ------------- | ---------- |
| **Light (Scepi)** | `ui-scepi-light-widget` | Animated bulb with on/off, optional dimmer/CT modals, bilingual labels, and an optional master visibility toggle. See [`docs/ui-light-scepi.md`](docs/ui-light-scepi.md). |
| **Window (Scepi)** | `ui-scepi-window-widget` | Smart-film toggle + shutter controls, selectable status text/dots, and optional master visibility toggle for hiding/showing widget groups. See [`docs/ui-window-scepi.md`](docs/ui-window-scepi.md). |
| **Switch (Scepi)** | `ui-switch-scepi` | Flexible on/off toggle with icon/status text controls, pass‑through mode, and runtime label overrides. See `docs/ui-switch-scepi.md`. |
| **Camera (Scepi)** | `ui-camera-scepi` | Still-image viewer for IP cameras, URLs, or base64 payloads with dynamic captions. See `docs/ui-camera-scepi.md`. |

Each widget exposes a matching editor form (`nodes/*.html`) so flows can turn individual UI modules (smart film, dimmer, CT, shutter buttons, status text, etc.) on or off without touching the Vue code. Runtime files (`nodes/*.js`) persist configuration via Dashboard 2.0’s `group.register` API, while the Vue Single File Components live in `ui/components/`.

## Installation

1. **Clone & install dependencies**
   ```bash
   git clone https://github.com/ScepiConsulting/scepi-ui.git
   cd node-red-scepi-ui
   npm install
   ```
2. **Develop inside Node-RED**  
   From your Node-RED `~/.node-red` user directory:
   ```bash
   npm install @scepi/node-red-dashboard-2-ui-package
   ```
   or use the Palette Manager and search for **“@scepi/node-red-dashboard-2-ui-package”**.

## Development Workflow

| Script | Description |
| ------ | ----------- |
| `npm run dev` | Watch/build all widgets with Vite in development mode. Keeps bundles in sync while Node-RED Dashboard is running. |
| `npm run dev:prod` | Same watcher but with production flags to catch minification issues early. |
| `npm run build` | One-shot production build; outputs `.umd.js` bundles to `resources/`. Run before publishing. |
| `npm run build:dev` | Production layout with development config to inspect bundles. |
| `npm run dev:<widget>` / `npm run build:<widget>` | Scope work to a single widget (`ui-switch-scepi`, `ui-camera-scepi`, etc.) via the `WIDGET` env var. |
| `npm run lint` | ESLint plus `sort-package-json --check`. Use `npm run lint:fix` to auto-fix. |

Recommended loop while building widgets:

1. `npm run dev`
2. Import the relevant node into a Dashboard 2.0 layout.
3. Exercise the widget (toggle dimmer, play with status flags, update `msg.ui_update` fields).
4. Finish with `npm run build` to regenerate the distributable UMD files.

## Project Layout

```
nodes/        # Node-RED runtime + editor definitions (JS/HTML/locales)
ui/components # Vue SFCs rendered inside Dashboard
ui/entries    # Vite entry points per widget
resources/    # Generated UMD bundles consumed by Dashboard
scripts/      # build/watch tooling
docs/         # Additional widget-specific docs (switch + camera)
examples/     # Importable Node-RED flow samples
```

- **Runtime flow**: Node-RED editor → `nodes/ui-*.html` → runtime `nodes/ui-*.js` → Vue component props (`ui/components/*`).  
- **State helpers**: Each runtime node uses `group.getBase()/register` so data & UI updates land in Dashboard stores (`base?.stores?.data/state`).  
- **Build**: `scripts/build-all.mjs` and `scripts/watch-all.mjs` wrap Vite and copy bundles into `resources/`.

## Widget Configuration Cheatsheet

### Light (Scepi)
- Location (HU / EN) + language switch.
- `showDimmer` & `showCT` checkboxes control whether dimmer or color-temperature modals render; missing flags default to off for backwards compatibility.
- Reacts to `msg.payload` (`on`, `brightness`, `colorTemp`, `variant`) and `msg.ui_update` fields.

### Window (Scepi)
- Toggles for smart-film control, shutter buttons, composite status text, window-status dot, and window-status copy.
- Position modal supports drag/scroll selection in 5% increments.
- Accepts runtime updates: `msg.payload` can set `shutterPosition`, `targetPosition`, `filmEnabled`, and `windowOpen`.

### Switch (Scepi)
- Label, icon, status text, pass-through, and output mode controls (input/output/both).
- Incoming `msg.label`, `msg.showIcon`, `msg.showStatus` override UI.

### Camera (Scepi)
- Displays `msg.payload` (URL or base64 data URI) with optional caption (`msg.caption` overrides the configured one).
- See `docs/ui-camera-scepi.md` for refresh strategies and example flows.

## Adding / Extending Widgets

1. Scaffold from `boilerplate/` or copy an existing widget folder.
2. Register the node in `package.json` under both `node-red.nodes` and `node-red-dashboard-2.widgets`.
3. Create matching files in `nodes/`, `ui/components/`, and `ui/entries/`.
4. Update `scripts/build-all.mjs` if the new widget requires special handling.
5. Run `npm run dev` and verify inside Dashboard 2.0.

Refer to `makingNewWidgets.md` and `publishing.md` for deeper guidance, including release steps (`npm run build` → `npm publish --access public`).

## Manual Testing Checklist

1. Start `npm run dev` and load a Dashboard 2.0 workspace.
2. Drag each widget into a layout and configure editor checkboxes:
   - Light: toggle dimmer/CT combinations.
   - Window: mix smart-film, shutter, status text/dots to ensure selective rendering.
   - Switch: verify icon/status toggles and pass-through settings.
   - Camera: send both URL and base64 payloads, override captions.
3. Trigger flows to confirm `msg.ui_update` fields persist location/language changes.
4. Finish with `npm run build` and load the fresh bundles in a clean Node-RED instance.

## Further Reading

- `docs/ui-light-scepi.md`
- `docs/ui-window-scepi.md`
- `docs/ui-switch-scepi.md`
- `docs/ui-camera-scepi.md`
- `project-notes.md`
- `makingNewWidgets.md`
- `publishing.md`

Happy hacking! If you ship improvements, please mention how you validated the widgets (lint, dev run, manual flow) in your PR descriptions.