@record-evolution/widget-scada 1.0.10 → 1.0.11

package/README.md

@@ -1,54 +1,127 @@
-# \<widget-SCADA>
+# \<widget-scada>
 
-This webcomponent follows the [open-wc](https://github.com/open-wc/open-wc) recommendation.
+Draws **one** industrial SCADA symbol — a tank, pipe, valve, pump, meter, breaker, panel — and
+animates it from live values: fill level, flow direction, running or stopped, opened or closed,
+warning, critical, leak. A process diagram is several of these widgets side by side, one per
+component.
 
-## Installation
+The symbols come from the [ThingsBoard](https://github.com/thingsboard/thingsboard) SCADA library:
+160 symbols in 12 categories, 132 of them clickable (a click sends a command to a device).
+
+## Installation & Usage
 
 ```bash
 npm i @record-evolution/widget-scada
 ```
 
-## Usage
-
 ```html
 <script type="module">
-    import '@record-evolution/widget-scada/widget-scada.js'
+    import '@record-evolution/widget-scada'
 </script>
 
-<widget-scada-0.0.1></widget-scada-0.0.1>
+<widget-scada-1.0.10></widget-scada-1.0.10>
+
+<script type="module">
+    const widget = document.querySelector('widget-scada-1.0.10')
+    widget.inputData = { symbol: 'centrifugal-pump', bindings: { running: true } }
+    widget.theme = { theme_name: 'light', theme_object: {} }
+    widget.addEventListener('action-submit', (e) => console.log(e.detail))
+</script>
 ```
 
-## Expected data format
+The element tag carries the package version (the build substitutes `versionplaceholder`), so several
+widget versions can coexist on one page. `demo/index.html` derives the tag from `package.json`, so
+keep the two in sync when you bump.
 
-Please take a look at the src/default-data.json to see what data is expected to make the widget show content.
+## Configuration (`inputData`)
 
-The following format represents the available data :
+`symbol` picks the SVG; everything else configures that one symbol:
 
-```js
-data: {
-  settings: {
-    title: string,
-    subTitle: string,
-    minGauge: number,
-    maxGauge: number,
-    style: {
-      needleColor: string,
-      sections: number,
-      backgroundColor: string[]
-    }
-  }
-  gaugeValue: Number
+```json
+{
+    "symbol": "left-analog-water-level-meter",
+    "bindings": { "running": true, "warning": false, "value": 10, "fullValue": 100 },
+    "styling": {},
+    "actions": {},
+    "showIcon": true,
+    "label": true,
+    "labelText": "Water",
+    "icon": "water",
+    "iconSize": 14
 }
 ```
 
-## SCADA Symbols
+| Group                   | What it is                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------- |
+| `symbol`                | Symbol id, one of the 160 in `scada_symbols/` — listed in `src/symbol-catalog.json` |
+| `bindings.*`            | The live booleans and numbers the symbol animates on. The only data-bindable group  |
+| `styling.*`             | Colors, fonts and sizes. Literal values only                                        |
+| `actions.*`             | Device, app and topic a click is sent to. Only meaningful on a clickable symbol     |
+| top-level display props | Per-symbol switches and texts (`showIcon`, `labelText`, connectors, thresholds, …)  |
+
+`src/definition-schema.json` is an **inverted union**: every property of every symbol lives in one
+flat schema, each gated by a `condition` listing the symbols it applies to. A key belonging to a
+different symbol than the selected one is therefore not an error — it is ignored at render time, and
+the dashboard editor strips it. `src/default-data.json` holds the demo configuration.
 
-The SVG SCADA symbols in `scada_symbols/` are taken from the [ThingsBoard](https://github.com/thingsboard/thingsboard) project and are licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). See [scada_symbols/LICENSE](scada_symbols/LICENSE) for details.
+## Generated files
 
-## Local Demo
+| File                         | Generator                         | Source                                                        |
+| ---------------------------- | --------------------------------- | ------------------------------------------------------------- |
+| `src/definition-schema.json` | `npm run schema`                  | The SVGs' `<tb:metadata>` plus `scripts/schema-curation.json` |
+| `src/definition-schema.d.ts` | `npm run types`                   | `json2ts` over the schema                                     |
+| `src/symbol-catalog.json`    | `npm run catalog`                 | Per-symbol summary for the AI widget builder                  |
+| `scada_symbols/index.json`   | `node scripts/generate-index.mjs` | Category index over the symbol SVGs                           |
+
+All four are committed, and `npm run release` regenerates them and refuses to release when the
+result differs from what is checked in.
+
+### Never hand-edit `definition-schema.json`
+
+It is generated, so an edit made in the file is lost on the next run. Anything the generator cannot
+derive from the SVG metadata — the AI selection hints, the curated symbol order and labels, the
+hand-written property descriptions, the per-symbol reading the union schema has to choose between
+(`label` is a `switch` on 9 symbols and a `text` field on 4) — belongs in
+**`scripts/schema-curation.json`**, which the generator applies as its last step.
 
 ```bash
-npm start
+npm run schema -- --check   # report drift, write nothing, exit 1 when the committed schema is behind
+npm run schema              # rewrite the schema, but only when the content actually changed
 ```
 
-To run a local development server that serves the basic demo located in `demo/index.html`
+`--check` is also the quick way to see what an edit to an SVG's metadata would do to the schema.
+
+## Symbol catalog
+
+`src/symbol-catalog.json` is what the platform's AI widget builder reads instead of the 233 KB
+schema — per symbol: label, category, description, search tags, natural grid size, aspect ratio,
+clickability, and the bindings it supports with their types. It is served from the published
+package:
+
+```
+https://cdn.jsdelivr.net/npm/@record-evolution/widget-scada@<version>/src/symbol-catalog.json
+```
+
+## Development
+
+```bash
+npm start    # vite dev server serving demo/index.html
+npm run link # develop against the local RESWARM frontend (npm run unlink to undo)
+```
+
+## Release
+
+```bash
+npm run release   # patch — release:minor / release:major for the others
+```
+
+`preversion` runs `scripts/release-preflight.sh` (on `main`, clean tree, in sync with origin,
+generators up to date, build passes); npm then bumps and tags; `postversion` pushes and waits for
+the publishing workflow, since publishing happens in CI rather than from a laptop.
+
+## SCADA Symbols
+
+The SVG SCADA symbols in `scada_symbols/` are taken from the
+[ThingsBoard](https://github.com/thingsboard/thingsboard) project and are licensed under the
+[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). See
+[scada_symbols/LICENSE](scada_symbols/LICENSE) for details.

package/dist/widget-scada.js

@@ -1178,7 +1178,7 @@ var de = Object.defineProperty, pe = Object.getOwnPropertyDescriptor, v = (n, t,
 };
 let y = class extends P {
   constructor() {
-    super(), this.svgContent = "", this.version = "1.0.10", this.svgModules = /* @__PURE__ */ new Map(), this.actionCleanups = [], this.resizeObserver = new ResizeObserver(() => this.requestUpdate()), this.resizeObserver.observe(this);
+    super(), this.svgContent = "", this.version = "1.0.11", this.svgModules = /* @__PURE__ */ new Map(), this.actionCleanups = [], this.resizeObserver = new ResizeObserver(() => this.requestUpdate()), this.resizeObserver.observe(this);
   }
   disconnectedCallback() {
     super.disconnectedCallback(), this.resizeObserver?.disconnect(), this.cleanupActions();
@@ -1354,7 +1354,7 @@ v([
   Yt(".svg-container")
 ], y.prototype, "svgContainer", 2);
 y = v([
-  Wt("widget-scada-1.0.10")
+  Wt("widget-scada-1.0.11")
 ], y);
 export {
   y as WidgetScada

package/package.json

@@ -3,7 +3,7 @@
     "description": "REWidget widget-SCADA",
     "license": "MIT",
     "author": "widget-SCADA",
-    "version": "1.0.10",
+    "version": "1.0.11",
     "engines": {
         "node": ">=24.9.0",
         "npm": ">=10.0.2"
@@ -25,9 +25,14 @@
         "watch": "vite build --watch",
         "link": "npm run build && npm link && cd ../RESWARM/frontend && npm link @record-evolution/widget-scada",
         "unlink": "npm unlink --global && cd ../RESWARM/frontend && npm unlink @record-evolution/widget-scada && npm i @record-evolution/widget-scada",
+        "schema": "node scripts/generate-schema.mjs",
         "types": "cat src/definition-schema.json | json2ts --style.tabWidth=4 > src/definition-schema.d.ts",
         "catalog": "node scripts/generate-catalog.mjs",
-        "release": "npm run build && npm run types && npm run catalog && npm version patch --tag-version-prefix='' && git push && git push --tag && npm run build"
+        "preversion": "sh scripts/release-preflight.sh",
+        "postversion": "git push --follow-tags && sh scripts/release-verify.sh",
+        "release": "npm version patch",
+        "release:minor": "npm version minor",
+        "release:major": "npm version major"
     },
     "dependencies": {
         "lit": "^3.3.3",
@@ -50,14 +55,14 @@
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/RecordEvolution/widget-SCADA.git"
+        "url": "git+https://github.com/RecordEvolution/widget-scada.git"
     },
     "keywords": [
         "widget",
         "scada"
     ],
     "bugs": {
-        "url": "https://github.com/RecordEvolution/widget-SCADA/issues"
+        "url": "https://github.com/RecordEvolution/widget-scada/issues"
     },
-    "homepage": "https://github.com/RecordEvolution/widget-SCADA#readme"
+    "homepage": "https://github.com/RecordEvolution/widget-scada#readme"
 }