@adcops/autocore-react 3.3.9 → 3.3.14

package/additional-docs/react_performance_notes.md

@@ -1,94 +1,94 @@
-# AutoCore React Performance & Architecture Notes
-
-## Overview
-
-This document details the architectural decisions and performance optimizations implemented in the `autocore-react` library, specifically regarding the `EventEmitterContext` and `AutoCoreTagContext`. These changes were made to solve issues with infinite re-render loops and performance bottlenecks when handling high-frequency sensor data (e.g., 50Hz+ updates).
-
-## Key Performance Rules
-
-### 1. Avoid Global Context State Updates for High-Frequency Data
-
-**The Problem:**
-Originally, `EventEmitterContext` stored the latest event payload in its state (`state.eventData`).
-Every time a WebSocket message arrived (e.g., a sensor value update), `setState` was called.
-Since `EventEmitterContext` wraps the entire application, **every single component in the app re-rendered** on every sensor update.
-
-**The Fix:**
-We removed the `setState` call from the `dispatch` function.
-- **Old way:** `dispatch` -> `setState` -> `Context Value Change` -> `App Re-render`.
-- **New way:** `dispatch` -> Iterate Subscribers -> `callback(payload)`.
-
-**Rule:**
-> Do NOT store high-frequency data (like sensor readings) in a global Context's `value` or `state` property if that Context is consumed by the root component. Use a subscription model (observers/listeners) instead.
-
-### 2. Stable Object References (Memoization)
-
-**The Problem:**
-In `AutoCoreTagContext`, the `scales` prop was defaulted using a destructuring assignment: `scales = {}`.
-This created a **new object reference** on every render.
-This unstable reference was used in `useEffect` dependency arrays, causing effects to re-run infinitely, leading to subscription storms and infinite loops.
-
-**The Fix:**
-We memoized the default empty object:
-```typescript
-const defaultScales = useMemo(() => ({}), []);
-const actualScales = scales ?? defaultScales;
-```
-And used `actualScales` everywhere.
-
-**Rule:**
-> Always ensure objects passed to Context Providers or used in `useEffect` dependencies are referentially stable. Use `useMemo` for derived objects and constants.
-
-### 3. Side-Effects in Render Phase
-
-**The Problem:**
-`EventEmitterProvider` was calling `hub.setContext(contextValue)` directly in the component body (during the render phase).
-React's Concurrent Mode or Strict Mode can call the render function multiple times without committing, leading to unpredictable state in the `Hub` singleton.
-
-**The Fix:**
-Moved the side-effect to `useEffect`:
-```typescript
-useEffect(() => {
-  hub.setContext(contextValue);
-}, [hub, contextValue]);
-```
-
-**Rule:**
-> Never mutate external Singletons or perform side-effects in the main body of a React Functional Component. Always use `useEffect`.
-
----
-
-## Data Flow Architecture
-
-### 1. Tag Name vs. FQDN
-
-To decouple the UI from the backend implementation:
-- **FQDN (Fully Qualified Domain Name)**: The backend address (e.g., `ADS.Main.bStart`). Used only for wire communication.
-- **TagName**: The local UI alias (e.g., `startCmd`). Used by React components.
-
-**The Flow:**
-1. **Component**: Calls `useAutoCoreTag("startCmd")`.
-2. **Context**: Looks up config, finds FQDN `ADS.Main.bStart`.
-3. **Context**: Calls `hub.subscribe("startCmd", "ADS.Main.bStart")`.
-4. **Hub**: Maps `ADS.Main.bStart` -> `startCmd`.
-5. **Backend**: Sends update for `ADS.Main.bStart`.
-6. **Hub**: Receives update, translates topic to `startCmd`, dispatches event.
-7. **Context**: Listens for `startCmd`, updates state.
-8. **Component**: Re-renders with new value.
-
-### 2. Dual-State Storage
-
-`AutoCoreTagContext` stores two versions of every value:
-1. **`rawValues`**: The exact JSON received from the server. **(Source of Truth)**
-2. **`values`**: The scaled/decoded value for display.
-
-When a scale changes (e.g., mm to inches), we recompute `values` from `rawValues`. We never rescale a previously scaled value to avoid floating-point drift.
-
----
-
-## Best Practices for Team
-
-1. **Use Hooks**: Always use `useAutoCoreTag` or `useAutoCoreTags`. Do not consume the Context directly unless necessary.
-2. **Key by TagName**: When adding features, always prefer `tagName` over `fqdn` for local logic.
-3. **Console Logs**: Avoid leaving `console.log` in render paths (components). It floods the console and slows down the browser.
-4. **Strict Mode**: Be aware that React Strict Mode mounts components twice. Your `useEffect` cleanup functions must be robust.
+# AutoCore React Performance & Architecture Notes
+
+## Overview
+
+This document details the architectural decisions and performance optimizations implemented in the `autocore-react` library, specifically regarding the `EventEmitterContext` and `AutoCoreTagContext`. These changes were made to solve issues with infinite re-render loops and performance bottlenecks when handling high-frequency sensor data (e.g., 50Hz+ updates).
+
+## Key Performance Rules
+
+### 1. Avoid Global Context State Updates for High-Frequency Data
+
+**The Problem:**
+Originally, `EventEmitterContext` stored the latest event payload in its state (`state.eventData`).
+Every time a WebSocket message arrived (e.g., a sensor value update), `setState` was called.
+Since `EventEmitterContext` wraps the entire application, **every single component in the app re-rendered** on every sensor update.
+
+**The Fix:**
+We removed the `setState` call from the `dispatch` function.
+- **Old way:** `dispatch` -> `setState` -> `Context Value Change` -> `App Re-render`.
+- **New way:** `dispatch` -> Iterate Subscribers -> `callback(payload)`.
+
+**Rule:**
+> Do NOT store high-frequency data (like sensor readings) in a global Context's `value` or `state` property if that Context is consumed by the root component. Use a subscription model (observers/listeners) instead.
+
+### 2. Stable Object References (Memoization)
+
+**The Problem:**
+In `AutoCoreTagContext`, the `scales` prop was defaulted using a destructuring assignment: `scales = {}`.
+This created a **new object reference** on every render.
+This unstable reference was used in `useEffect` dependency arrays, causing effects to re-run infinitely, leading to subscription storms and infinite loops.
+
+**The Fix:**
+We memoized the default empty object:
+```typescript
+const defaultScales = useMemo(() => ({}), []);
+const actualScales = scales ?? defaultScales;
+```
+And used `actualScales` everywhere.
+
+**Rule:**
+> Always ensure objects passed to Context Providers or used in `useEffect` dependencies are referentially stable. Use `useMemo` for derived objects and constants.
+
+### 3. Side-Effects in Render Phase
+
+**The Problem:**
+`EventEmitterProvider` was calling `hub.setContext(contextValue)` directly in the component body (during the render phase).
+React's Concurrent Mode or Strict Mode can call the render function multiple times without committing, leading to unpredictable state in the `Hub` singleton.
+
+**The Fix:**
+Moved the side-effect to `useEffect`:
+```typescript
+useEffect(() => {
+  hub.setContext(contextValue);
+}, [hub, contextValue]);
+```
+
+**Rule:**
+> Never mutate external Singletons or perform side-effects in the main body of a React Functional Component. Always use `useEffect`.
+
+---
+
+## Data Flow Architecture
+
+### 1. Tag Name vs. FQDN
+
+To decouple the UI from the backend implementation:
+- **FQDN (Fully Qualified Domain Name)**: The backend address (e.g., `ADS.Main.bStart`). Used only for wire communication.
+- **TagName**: The local UI alias (e.g., `startCmd`). Used by React components.
+
+**The Flow:**
+1. **Component**: Calls `useAutoCoreTag("startCmd")`.
+2. **Context**: Looks up config, finds FQDN `ADS.Main.bStart`.
+3. **Context**: Calls `hub.subscribe("startCmd", "ADS.Main.bStart")`.
+4. **Hub**: Maps `ADS.Main.bStart` -> `startCmd`.
+5. **Backend**: Sends update for `ADS.Main.bStart`.
+6. **Hub**: Receives update, translates topic to `startCmd`, dispatches event.
+7. **Context**: Listens for `startCmd`, updates state.
+8. **Component**: Re-renders with new value.
+
+### 2. Dual-State Storage
+
+`AutoCoreTagContext` stores two versions of every value:
+1. **`rawValues`**: The exact JSON received from the server. **(Source of Truth)**
+2. **`values`**: The scaled/decoded value for display.
+
+When a scale changes (e.g., mm to inches), we recompute `values` from `rawValues`. We never rescale a previously scaled value to avoid floating-point drift.
+
+---
+
+## Best Practices for Team
+
+1. **Use Hooks**: Always use `useAutoCoreTag` or `useAutoCoreTags`. Do not consume the Context directly unless necessary.
+2. **Key by TagName**: When adding features, always prefer `tagName` over `fqdn` for local logic.
+3. **Console Logs**: Avoid leaving `console.log` in render paths (components). It floods the console and slows down the browser.
+4. **Strict Mode**: Be aware that React Strict Mode mounts components twice. Your `useEffect` cleanup functions must be robust.

package/dist/assets/svg/blockly_logo.svg

@@ -1,82 +1,82 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!-- Created with Inkscape (http://www.inkscape.org/) -->
-
-<svg
-   width="34.131214"
-   height="38.056591"
-   viewBox="0 0 34.131214 38.056592"
-   version="1.1"
-   id="svg1512"
-   inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)"
-   sodipodi:docname="blockly_icon.svg"
-   inkscape:export-filename="/usr/local/google/home/epastern/Documents/Blockly Logos/Square/logo_standard.png"
-   inkscape:export-xdpi="96"
-   inkscape:export-ydpi="96"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:dc="http://purl.org/dc/elements/1.1/">
-  <defs
-     id="defs1506" />
-  <sodipodi:namedview
-     id="base"
-     pagecolor="#ffffff"
-     bordercolor="#666666"
-     borderopacity="1.0"
-     inkscape:pageopacity="0.0"
-     inkscape:pageshadow="2"
-     inkscape:zoom="0.7"
-     inkscape:cx="-31.428571"
-     inkscape:cy="-36.428571"
-     inkscape:document-units="px"
-     inkscape:current-layer="layer1"
-     showgrid="false"
-     inkscape:measure-start="215.162,827.567"
-     inkscape:measure-end="164.907,827.567"
-     fit-margin-top="10"
-     fit-margin-right="10"
-     fit-margin-bottom="10"
-     fit-margin-left="10"
-     inkscape:window-width="2400"
-     inkscape:window-height="1494"
-     inkscape:window-x="-11"
-     inkscape:window-y="-11"
-     inkscape:window-maximized="1"
-     inkscape:showpageshadow="0"
-     inkscape:pagecheckerboard="0"
-     inkscape:deskcolor="#c8c8c8"
-     showborder="false"
-     borderlayer="false" />
-  <metadata
-     id="metadata1509">
-    <rdf:RDF>
-      <cc:Work
-         rdf:about="">
-        <dc:format>image/svg+xml</dc:format>
-        <dc:type
-           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-      </cc:Work>
-    </rdf:RDF>
-  </metadata>
-  <g
-     inkscape:label="Layer 1"
-     inkscape:groupmode="layer"
-     id="layer1"
-     transform="translate(-9.3927263,-61.769323)">
-    <path
-       id="path906"
-       d="m 12.604934,61.770873 c -1.774567,-0.0015 -3.2136701,1.43764 -3.2122066,3.212207 v 27.706838 c -0.00146,1.774568 1.4376396,3.213669 3.2122066,3.212205 h 1.25057 c 0.616698,2.31294 2.710855,3.922673 5.104598,3.923792 2.392205,-0.003 4.484163,-1.612336 5.100464,-3.923792 h 1.281058 4.160987 c 1.169002,0 2.116666,-0.947663 2.116666,-2.116666 V 63.88754 l -2.116666,-2.116667 z"
-       style="fill:#4285f4;stroke-width:0.264583"
-       inkscape:connector-curvature="0"
-       sodipodi:nodetypes="ccccccccssccc" />
-    <path
-       sodipodi:nodetypes="ccccccccccccccccc"
-       inkscape:connector-curvature="0"
-       id="path908"
-       d="m 28.444794,61.769323 c -0.0028,4.683852 -0.0021,9.366881 -0.0021,14.053406 l -4.400251,-2.48667 c -0.634301,-0.357915 -1.419291,0.09954 -1.420585,0.827856 V 84.91158 c 0.0013,0.728311 0.786285,1.18577 1.420585,0.827855 l 4.400248,-2.487186 v 9.946164 0.587044 2.116666 h 2.116667 0.377238 9.539468 c 1.683266,-6.8e-5 3.047807,-1.364609 3.047876,-3.047875 V 64.808414 c -0.0057,-1.679229 -1.368601,-3.037482 -3.04784,-3.037541 z"
-       style="fill:#c8d1db;stroke-width:0.264583" />
-  </g>
-</svg>
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="34.131214"
+   height="38.056591"
+   viewBox="0 0 34.131214 38.056592"
+   version="1.1"
+   id="svg1512"
+   inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)"
+   sodipodi:docname="blockly_icon.svg"
+   inkscape:export-filename="/usr/local/google/home/epastern/Documents/Blockly Logos/Square/logo_standard.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <defs
+     id="defs1506" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.7"
+     inkscape:cx="-31.428571"
+     inkscape:cy="-36.428571"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:measure-start="215.162,827.567"
+     inkscape:measure-end="164.907,827.567"
+     fit-margin-top="10"
+     fit-margin-right="10"
+     fit-margin-bottom="10"
+     fit-margin-left="10"
+     inkscape:window-width="2400"
+     inkscape:window-height="1494"
+     inkscape:window-x="-11"
+     inkscape:window-y="-11"
+     inkscape:window-maximized="1"
+     inkscape:showpageshadow="0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#c8c8c8"
+     showborder="false"
+     borderlayer="false" />
+  <metadata
+     id="metadata1509">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-9.3927263,-61.769323)">
+    <path
+       id="path906"
+       d="m 12.604934,61.770873 c -1.774567,-0.0015 -3.2136701,1.43764 -3.2122066,3.212207 v 27.706838 c -0.00146,1.774568 1.4376396,3.213669 3.2122066,3.212205 h 1.25057 c 0.616698,2.31294 2.710855,3.922673 5.104598,3.923792 2.392205,-0.003 4.484163,-1.612336 5.100464,-3.923792 h 1.281058 4.160987 c 1.169002,0 2.116666,-0.947663 2.116666,-2.116666 V 63.88754 l -2.116666,-2.116667 z"
+       style="fill:#4285f4;stroke-width:0.264583"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="ccccccccssccc" />
+    <path
+       sodipodi:nodetypes="ccccccccccccccccc"
+       inkscape:connector-curvature="0"
+       id="path908"
+       d="m 28.444794,61.769323 c -0.0028,4.683852 -0.0021,9.366881 -0.0021,14.053406 l -4.400251,-2.48667 c -0.634301,-0.357915 -1.419291,0.09954 -1.420585,0.827856 V 84.91158 c 0.0013,0.728311 0.786285,1.18577 1.420585,0.827855 l 4.400248,-2.487186 v 9.946164 0.587044 2.116666 h 2.116667 0.377238 9.539468 c 1.683266,-6.8e-5 3.047807,-1.364609 3.047876,-3.047875 V 64.808414 c -0.0057,-1.679229 -1.368601,-3.037482 -3.04784,-3.037541 z"
+       style="fill:#c8d1db;stroke-width:0.264583" />
+  </g>
+</svg>

package/dist/assets/svg/distance.svg

@@ -1,40 +1,40 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg
-   height="24"
-   viewBox="0 -960 960 960"
-   width="24"
-   fill="white"
-   version="1.1"
-   id="svg1"
-   sodipodi:docname="distance.svg"
-   inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:svg="http://www.w3.org/2000/svg">
-  <defs
-     id="defs1" />
-  <sodipodi:namedview
-     id="namedview1"
-     pagecolor="#505050"
-     bordercolor="#eeeeee"
-     borderopacity="1"
-     inkscape:showpageshadow="0"
-     inkscape:pageopacity="0"
-     inkscape:pagecheckerboard="0"
-     inkscape:deskcolor="#505050"
-     showgrid="false"
-     inkscape:zoom="33.875"
-     inkscape:cx="12"
-     inkscape:cy="12"
-     inkscape:window-width="1920"
-     inkscape:window-height="1009"
-     inkscape:window-x="1912"
-     inkscape:window-y="-8"
-     inkscape:window-maximized="1"
-     inkscape:current-layer="svg1" />
-  <path
-     d="m 99.28704,-194.46528 q -39.261024,0 -67.219632,-27.95861 Q 4.1088,-250.3825 4.1088,-289.64352 v -380.71296 q 0,-39.26102 27.958608,-67.21963 27.958608,-27.95861 67.219632,-27.95861 h 761.42592 q 39.26102,0 67.21963,27.95861 27.95861,27.95861 27.95861,67.21963 v 380.71296 q 0,39.26102 -27.95861,67.21963 -27.95861,27.95861 -67.21963,27.95861 z m 0,-95.17824 H 860.71296 V -670.35648 H 717.9456 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 690.58186,-480 670.35648,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 v -142.76736 h -95.17824 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 500.22538,-480 480,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 v -142.76736 h -95.17824 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 309.8689,-480 289.64352,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 V -670.35648 H 99.28704 Z M 289.64352,-480 Z M 480,-480 Z m 190.35648,0 z M 480,-480 Z"
-     id="path1"
-     style="stroke-width:1.18973" />
-</svg>
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   height="24"
+   viewBox="0 -960 960 960"
+   width="24"
+   fill="white"
+   version="1.1"
+   id="svg1"
+   sodipodi:docname="distance.svg"
+   inkscape:version="1.3.2 (091e20e, 2023-11-25, custom)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <defs
+     id="defs1" />
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#505050"
+     bordercolor="#eeeeee"
+     borderopacity="1"
+     inkscape:showpageshadow="0"
+     inkscape:pageopacity="0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#505050"
+     showgrid="false"
+     inkscape:zoom="33.875"
+     inkscape:cx="12"
+     inkscape:cy="12"
+     inkscape:window-width="1920"
+     inkscape:window-height="1009"
+     inkscape:window-x="1912"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg1" />
+  <path
+     d="m 99.28704,-194.46528 q -39.261024,0 -67.219632,-27.95861 Q 4.1088,-250.3825 4.1088,-289.64352 v -380.71296 q 0,-39.26102 27.958608,-67.21963 27.958608,-27.95861 67.219632,-27.95861 h 761.42592 q 39.26102,0 67.21963,27.95861 27.95861,27.95861 27.95861,67.21963 v 380.71296 q 0,39.26102 -27.95861,67.21963 -27.95861,27.95861 -67.21963,27.95861 z m 0,-95.17824 H 860.71296 V -670.35648 H 717.9456 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 690.58186,-480 670.35648,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 v -142.76736 h -95.17824 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 500.22538,-480 480,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 v -142.76736 h -95.17824 v 142.76736 q 0,20.22538 -13.68187,33.90725 Q 309.8689,-480 289.64352,-480 q -20.22538,0 -33.90725,-13.68187 -13.68187,-13.68187 -13.68187,-33.90725 V -670.35648 H 99.28704 Z M 289.64352,-480 Z M 480,-480 Z m 190.35648,0 z M 480,-480 Z"
+     id="path1"
+     style="stroke-width:1.18973" />
+</svg>