@adcops/autocore-react 3.3.9 → 3.3.14

package/readme.md

@@ -1,344 +1,344 @@
-# autocore-react
-
-React components for HTML5 user interfaces that are easy to integrate into any project. autocore-react
-targets both the browser and Tauri. The primary focus is HMI applications for machine control, as well
-as tasks common to general desktop applications.
-
-## Overview
-
-autocore is ADC's collection of Industry 4.0 (IIOT) libraries. autocore-react focuses on user interface
-development.
-
-autocore-react is the third version of this library, and is a simplification of previous versions. Instead
-of relying on dozens of custom controls for integration into HMI applications, autocore-react now leans on
-PrimeReact to supply almost all but the most obscure controls, and adds a wrapper to integrate
-signals from the backend to the common controls. This allows autocore-react to focus on the additional
-features needed for machine-control user interfaces, while PrimeReact excels at development of components.
-
-## Installation
-
-Install from NPM.
-
-```
-npm install --save @adcops/autocore-react
-```
-
-## Quick Start
-
-### 1. Define Your Tags
-
-Create `AutoCoreTags.ts` to define all the tags your application will use:
-
-```typescript
-import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
-
-export const acTagSpec = [
-  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
-  { "tagName": "motorSpeed", "domain": "ADS", "symbolName": "MAIN.ctx.motor.fSpeed", "valueType": "number" },
-  { "tagName": "isAutoCycleRunning", "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
-  { "tagName": "positionScalar", "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number", "initialValue": 1.0 }
-] as const satisfies readonly TagConfig[];
-
-export default acTagSpec;
-```
-
-### 2. Create Typed Hooks
-
-Create `AutoCore.ts` to generate strongly-typed hooks:
-
-```typescript
-import { acTagSpec } from "./AutoCoreTags";
-import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
-import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
-
-export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
-```
-
-
-#### Define Scales (Optional)
-For applications that need unit conversion, create `AutoCoreScales.ts` with server-driven scaling:
-
-
-```tsx
-import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
-
-export const acScales = {
-  position: { 
-    name: "position", 
-    scale: 1.0, 
-    label: "mm",
-    serverTag: { domain: "GNV", symbolName: "position_scalar" }
-  },
-  load: { 
-    name: "load", 
-    scale: 1.0, 
-    label: "N",
-    serverTag: { domain: "GNV", symbolName: "load_scalar" }
-  }
-} as const satisfies Record<string, ScaleConfig>;
-```
-
-Note: Server tags now store both scale factor and label as a JSON object: `{ scale: 1.0, label: "mm" }`. Legacy numeric-only values are supported for backward compatibility.
-
-Next, reference scales in your tag definitions.
-
-```tsx
-// In AutoCoreTags.ts - add scale property to numeric tags
-{ "tagName": "pressPosition", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number", "scale": "position" },
-{ "tagName": "pressLoad", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number", "scale": "load" }
-```
-
-### 3. Wrap Your App
-
-Update your `App.tsx` to provide the contexts:
-
-```typescript
-import React from 'react';
-import { PrimeReactProvider } from 'primereact/api';
-import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext";
-import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
-import { acTagSpec } from "./AutoCoreTags";
-import { acScales } from "./AutoCoreScales";
-
-function App() {
-  return (
-    <EventEmitterProvider>
-      <PrimeReactProvider>
-        <AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
-          <div className="app-wrapper">
-            <main className="main-wrapper">
-              <YourMainContent />
-            </main>
-          </div>
-        </AutoCoreTagProvider>
-      </PrimeReactProvider>
-    </EventEmitterProvider>
-  );
-}
-
-export default App;
-```
-
-### 4. Use Tags in Components
-
-Import your typed hooks and use them in any component:
-
-```typescript
-import React from 'react';
-import { Button } from 'primereact/button';
-import { AutoCoreHooks } from './AutoCore';
-
-export const ControlPanel: React.FC = () => {
-  // Single tag access
-  const { value: powerOk, write: setPowerOk } = AutoCoreHooks.useAutoCoreTag("isControlPowerOk");
-  const { value: motorSpeed, write: setMotorSpeed } = AutoCoreHooks.useAutoCoreTag("motorSpeed");
-  
-  // Multiple tag access
-  const { values } = AutoCoreHooks.useAutoCoreTags(["isControlPowerOk", "isAutoCycleRunning"]);
-  
-  // Computed state
-  const { selected: canStart } = AutoCoreHooks.useAutoCoreSelect(v =>
-    !!v["isControlPowerOk"] && !v["isAutoCycleRunning"]
-  );
-
-  return (
-    <div>
-      <div>Power OK: {powerOk ? "Yes" : "No"}</div>
-      <div>Motor Speed: {motorSpeed} RPM</div>
-      
-      <Button 
-        label="Start Motor" 
-        disabled={!canStart}
-        onClick={() => setMotorSpeed(1000)}
-      />
-      
-      <Button 
-        label="Emergency Stop" 
-        severity="danger"
-        onClick={() => setPowerOk(false)}
-      />
-    </div>
-  );
-};
-```
-
-### 5. Development Panel (Optional)
-
-Add a debugging panel for development:
-
-```typescript
-import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
-import { acTagSpec } from "./AutoCoreTags";
-
-// In your App component:
-{process.env.NODE_ENV === 'development' && (
-  <AutoCoreDevPanel 
-    tags={acTagSpec} 
-    className="fixed bottom-4 right-4 bg-white shadow-lg" 
-  />
-)}
-```
-
-## AutoCoreTagContext Features
-
-- **Strongly-typed**: Full TypeScript support with IntelliSense for tag names and value types
-- **Global state**: Share tag values across your entire application
-- **Real-time updates**: Automatic subscription to server data changes
-- **No optimistic updates**: UI always reflects true server state
-- **Error handling**: Proper async/await patterns with error feedback
-- **Development tools**: Built-in debugging panel for testing
-
-## Architecture
-
-### Hub (Internal)
-
-The Hub is an internal abstraction that handles communication with the backend. It automatically
-selects the proper pipeline based on the environment: HubTauri for Tauri applications, socket.io 
-for browser instances, and a simulated backend for development environments.
-
-**Important**: Applications should not interact with the Hub directly. Instead, use the higher-level 
-abstractions described below.
-
-### EventEmitterContext
-
-The EventEmitterContext provides a global event system for component communication and backend 
-interaction through `invoke()`, `subscribe()`, and `dispatch()` methods. This is automatically 
-available when you wrap your app with `<EventEmitterProvider>`.
-
-### AutoCoreTagContext (Recommended)
-
-For most backend data interactions, use the AutoCoreTagContext system with strongly-typed hooks.
-This provides the cleanest, most maintainable approach for managing server state in your components.
-See the Quick Start section above for setup and usage.
-
-## Development
-
-We typically have an external Tauri project designed to import and test the autocore-react library. We find that
-some issues, particularly Singleton classes and certain resources, may not occur when components are tested 
-within the same project.
-
-There are multiple ways to test a "pre-release" or "staging" version of the library before publishing the official version.
-
-### Use npm tags to publish a "staging" version
-
-Use this for a final "pre-flight check" or when testing a serious release candidate. For development with frequent changes, use 'npm link.'
-
-When you publish a package to npm, it automatically assigns the latest tag to the published version. Most users will install the latest version when they omit a tag/version in the npm install command. To publish a "staging" or pre-release version without affecting users of the latest version, you can use a custom tag, such as next, beta, or staging.
-
-To publish a "staging" version of your package, you can run:
-```
-npm publish --tag staging --access=public
-```
-
-Note that we have to specify that the access is public because the tag makes this "scoped," which are private by default.
-
-In the test project, simply install the 'staging' tag version.
-
-```
-npm install @adcops/autocore-react@staging
-```
-
-### npm link
-
-In the root of the autocore-react project, initiate npm link:
-
-```
-npm link
-```
-
-Now, the autocore-react project is being served locally to your machine.
-
-To test it in an external project, navigate to the root directory of that project.
-
-```
-npm link @adcops/autocore-react
-```
-
-Whatever current version of autocore-react will be removed and replaced with links to the
-project directory on your machine. The nice thing is that, as you make machines in the
-autocore-react project, those changes are reflected immediately in the external project.
-The downside is that not every file can be served by npm link in this way. For example,
-were there font files and icon resources served from autocore-react, the wouldn't load
-into the external project because of CORS limitation. Depending on what you're testing,
-this may not matter.
-
-When done testing, in the external project we simply unlink.
-
-```
-npm unlink @adcops/autocore-react
-```
-
-A final consequence is that, were autocore-react installed  before using npm link, it will
-no longer be installed once unlink. You will once again need to install the latest
-published version, if so desired.
-
-```
-npm install --save @adcops/autocore-react
-```
-
-## Image assets
-
-First, always first check PrimeReact at [primereact.org/icons](https://primereact.org/icons/ "primereact.org/icons") to see if an icon with the
-proper meaning or look exists. If so, always prefer use of a built-in PrimeReact icon.
-
-That being said, the PrimeReact icon library isn't written with the industrial market in mind. We've customized and created additional icons with 
-specific meaning in industrial use. 
-
-We create the SVGs by starting with an SVG from Material Icons that closely resembles our needs, then modify using InkScape or, more often than not, by adjusting
-the path by hand. Once ready, we place the file into `./src/assets/svg`.
-
-However, since we're not using a bundler, it's much easier and more reliable to import by converting the SVG file 
-to a .tsx file, making it a component that can be imported in our source file. For that task, we use the command-line version of SVGR.
-
-The package.json file contains a script for running SVGR properly. Running `npm run convert-assets` will process all .svg files in ./src/assets/svg into
-.tsx files located in ./src/assets. To use one of the newly-generated components, simply import as you would any component.
-
-```
-import { JogLong } from '../assets';
-
-<JogLong className="distance-selector-button" width={16} height={16} />
-```
-
-Note that hand-editing out some features out of the TSX file is often required. Because of that, the convert-assests command is set not to
-overwrite existing .tsx files. If you need to update a pre-existing .tsx file, delete it first.
-
-Possible options for SVGR:
-https://react-svgr.com/docs/options/
-
-## Documentation
-
-To generate documentation:
-```
-npm run generate-docs
-```
-
-Publishing the package will also regenerate the documentation.
-
-## Additional Documentation
-
-Beyond doc-comments in the code, we provide additional documentation in the additional-docs folder.
-
-- AutoCoreTagContext Manual: [AutoCoreTagContext Manual](../additional-docs/AutoCoreTagContext.md).
-- Button API Specs: [Button API Specs](../additional-docs/ButtonApiSpecs.md).
-- Global Event Emitter: [Global Event Emitter](../additional-docs/GlobalEventEmitter.md).
-
-## Acknowledgements
-
-Beyond the obvious, inherent React and TypeScript libraries, autocore-react greatly appreciates the works of
-these additional libraries.
-
-- PrimeReact and PrimeIcons
-- numerable
-- Simple Keyboard (https://github.com/hodgef/simple-keyboard)
-- - We customize Simple Keyboard for cleaner physical keyboard integration.
-- Monaco editor
-- socket-io
-- Tauri
-
-## Copyright
-
-(C) Copyright 2021-2025 Automated Design Corp. All Rights Reserved.
-
-## License
-
+# autocore-react
+
+React components for HTML5 user interfaces that are easy to integrate into any project. autocore-react
+targets both the browser and Tauri. The primary focus is HMI applications for machine control, as well
+as tasks common to general desktop applications.
+
+## Overview
+
+autocore is ADC's collection of Industry 4.0 (IIOT) libraries. autocore-react focuses on user interface
+development.
+
+autocore-react is the third version of this library, and is a simplification of previous versions. Instead
+of relying on dozens of custom controls for integration into HMI applications, autocore-react now leans on
+PrimeReact to supply almost all but the most obscure controls, and adds a wrapper to integrate
+signals from the backend to the common controls. This allows autocore-react to focus on the additional
+features needed for machine-control user interfaces, while PrimeReact excels at development of components.
+
+## Installation
+
+Install from NPM.
+
+```
+npm install --save @adcops/autocore-react
+```
+
+## Quick Start
+
+### 1. Define Your Tags
+
+Create `AutoCoreTags.ts` to define all the tags your application will use:
+
+```typescript
+import type { TagConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acTagSpec = [
+  { "tagName": "isControlPowerOk", "domain": "ADS", "symbolName": "GIO.xbControlPowerOk", "valueType": "boolean" },
+  { "tagName": "motorSpeed", "domain": "ADS", "symbolName": "MAIN.ctx.motor.fSpeed", "valueType": "number" },
+  { "tagName": "isAutoCycleRunning", "domain": "ADS", "symbolName": "MAIN.ctx.gm.bAutoCycleRunning", "valueType": "boolean" },
+  { "tagName": "positionScalar", "domain": "MEMORYSTORE", "symbolName": "position_scalar", "valueType": "number", "initialValue": 1.0 }
+] as const satisfies readonly TagConfig[];
+
+export default acTagSpec;
+```
+
+### 2. Create Typed Hooks
+
+Create `AutoCore.ts` to generate strongly-typed hooks:
+
+```typescript
+import { acTagSpec } from "./AutoCoreTags";
+import { AutoCoreTagContext } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { makeAutoCoreTagHooks } from "@adcops/autocore-react/hooks/useAutoCoreTag";
+
+export const AutoCoreHooks = makeAutoCoreTagHooks(AutoCoreTagContext, acTagSpec);
+```
+
+
+#### Define Scales (Optional)
+For applications that need unit conversion, create `AutoCoreScales.ts` with server-driven scaling:
+
+
+```tsx
+import { ScaleConfig } from "@adcops/autocore-react/core/AutoCoreTagTypes";
+
+export const acScales = {
+  position: { 
+    name: "position", 
+    scale: 1.0, 
+    label: "mm",
+    serverTag: { domain: "GNV", symbolName: "position_scalar" }
+  },
+  load: { 
+    name: "load", 
+    scale: 1.0, 
+    label: "N",
+    serverTag: { domain: "GNV", symbolName: "load_scalar" }
+  }
+} as const satisfies Record<string, ScaleConfig>;
+```
+
+Note: Server tags now store both scale factor and label as a JSON object: `{ scale: 1.0, label: "mm" }`. Legacy numeric-only values are supported for backward compatibility.
+
+Next, reference scales in your tag definitions.
+
+```tsx
+// In AutoCoreTags.ts - add scale property to numeric tags
+{ "tagName": "pressPosition", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressPosition", "valueType": "number", "scale": "position" },
+{ "tagName": "pressLoad", "domain": "ADS", "symbolName": "MAIN.ctx.gm.fPressLoad", "valueType": "number", "scale": "load" }
+```
+
+### 3. Wrap Your App
+
+Update your `App.tsx` to provide the contexts:
+
+```typescript
+import React from 'react';
+import { PrimeReactProvider } from 'primereact/api';
+import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext";
+import { AutoCoreTagProvider } from "@adcops/autocore-react/core/AutoCoreTagContext";
+import { acTagSpec } from "./AutoCoreTags";
+import { acScales } from "./AutoCoreScales";
+
+function App() {
+  return (
+    <EventEmitterProvider>
+      <PrimeReactProvider>
+        <AutoCoreTagProvider tags={acTagSpec} scales={acScales} eagerRead>
+          <div className="app-wrapper">
+            <main className="main-wrapper">
+              <YourMainContent />
+            </main>
+          </div>
+        </AutoCoreTagProvider>
+      </PrimeReactProvider>
+    </EventEmitterProvider>
+  );
+}
+
+export default App;
+```
+
+### 4. Use Tags in Components
+
+Import your typed hooks and use them in any component:
+
+```typescript
+import React from 'react';
+import { Button } from 'primereact/button';
+import { AutoCoreHooks } from './AutoCore';
+
+export const ControlPanel: React.FC = () => {
+  // Single tag access
+  const { value: powerOk, write: setPowerOk } = AutoCoreHooks.useAutoCoreTag("isControlPowerOk");
+  const { value: motorSpeed, write: setMotorSpeed } = AutoCoreHooks.useAutoCoreTag("motorSpeed");
+  
+  // Multiple tag access
+  const { values } = AutoCoreHooks.useAutoCoreTags(["isControlPowerOk", "isAutoCycleRunning"]);
+  
+  // Computed state
+  const { selected: canStart } = AutoCoreHooks.useAutoCoreSelect(v =>
+    !!v["isControlPowerOk"] && !v["isAutoCycleRunning"]
+  );
+
+  return (
+    <div>
+      <div>Power OK: {powerOk ? "Yes" : "No"}</div>
+      <div>Motor Speed: {motorSpeed} RPM</div>
+      
+      <Button 
+        label="Start Motor" 
+        disabled={!canStart}
+        onClick={() => setMotorSpeed(1000)}
+      />
+      
+      <Button 
+        label="Emergency Stop" 
+        severity="danger"
+        onClick={() => setPowerOk(false)}
+      />
+    </div>
+  );
+};
+```
+
+### 5. Development Panel (Optional)
+
+Add a debugging panel for development:
+
+```typescript
+import { AutoCoreDevPanel } from "@adcops/autocore-react/components/AutoCoreDevPanel";
+import { acTagSpec } from "./AutoCoreTags";
+
+// In your App component:
+{process.env.NODE_ENV === 'development' && (
+  <AutoCoreDevPanel 
+    tags={acTagSpec} 
+    className="fixed bottom-4 right-4 bg-white shadow-lg" 
+  />
+)}
+```
+
+## AutoCoreTagContext Features
+
+- **Strongly-typed**: Full TypeScript support with IntelliSense for tag names and value types
+- **Global state**: Share tag values across your entire application
+- **Real-time updates**: Automatic subscription to server data changes
+- **No optimistic updates**: UI always reflects true server state
+- **Error handling**: Proper async/await patterns with error feedback
+- **Development tools**: Built-in debugging panel for testing
+
+## Architecture
+
+### Hub (Internal)
+
+The Hub is an internal abstraction that handles communication with the backend. It automatically
+selects the proper pipeline based on the environment: HubTauri for Tauri applications, socket.io 
+for browser instances, and a simulated backend for development environments.
+
+**Important**: Applications should not interact with the Hub directly. Instead, use the higher-level 
+abstractions described below.
+
+### EventEmitterContext
+
+The EventEmitterContext provides a global event system for component communication and backend 
+interaction through `invoke()`, `subscribe()`, and `dispatch()` methods. This is automatically 
+available when you wrap your app with `<EventEmitterProvider>`.
+
+### AutoCoreTagContext (Recommended)
+
+For most backend data interactions, use the AutoCoreTagContext system with strongly-typed hooks.
+This provides the cleanest, most maintainable approach for managing server state in your components.
+See the Quick Start section above for setup and usage.
+
+## Development
+
+We typically have an external Tauri project designed to import and test the autocore-react library. We find that
+some issues, particularly Singleton classes and certain resources, may not occur when components are tested 
+within the same project.
+
+There are multiple ways to test a "pre-release" or "staging" version of the library before publishing the official version.
+
+### Use npm tags to publish a "staging" version
+
+Use this for a final "pre-flight check" or when testing a serious release candidate. For development with frequent changes, use 'npm link.'
+
+When you publish a package to npm, it automatically assigns the latest tag to the published version. Most users will install the latest version when they omit a tag/version in the npm install command. To publish a "staging" or pre-release version without affecting users of the latest version, you can use a custom tag, such as next, beta, or staging.
+
+To publish a "staging" version of your package, you can run:
+```
+npm publish --tag staging --access=public
+```
+
+Note that we have to specify that the access is public because the tag makes this "scoped," which are private by default.
+
+In the test project, simply install the 'staging' tag version.
+
+```
+npm install @adcops/autocore-react@staging
+```
+
+### npm link
+
+In the root of the autocore-react project, initiate npm link:
+
+```
+npm link
+```
+
+Now, the autocore-react project is being served locally to your machine.
+
+To test it in an external project, navigate to the root directory of that project.
+
+```
+npm link @adcops/autocore-react
+```
+
+Whatever current version of autocore-react will be removed and replaced with links to the
+project directory on your machine. The nice thing is that, as you make machines in the
+autocore-react project, those changes are reflected immediately in the external project.
+The downside is that not every file can be served by npm link in this way. For example,
+were there font files and icon resources served from autocore-react, the wouldn't load
+into the external project because of CORS limitation. Depending on what you're testing,
+this may not matter.
+
+When done testing, in the external project we simply unlink.
+
+```
+npm unlink @adcops/autocore-react
+```
+
+A final consequence is that, were autocore-react installed  before using npm link, it will
+no longer be installed once unlink. You will once again need to install the latest
+published version, if so desired.
+
+```
+npm install --save @adcops/autocore-react
+```
+
+## Image assets
+
+First, always first check PrimeReact at [primereact.org/icons](https://primereact.org/icons/ "primereact.org/icons") to see if an icon with the
+proper meaning or look exists. If so, always prefer use of a built-in PrimeReact icon.
+
+That being said, the PrimeReact icon library isn't written with the industrial market in mind. We've customized and created additional icons with 
+specific meaning in industrial use. 
+
+We create the SVGs by starting with an SVG from Material Icons that closely resembles our needs, then modify using InkScape or, more often than not, by adjusting
+the path by hand. Once ready, we place the file into `./src/assets/svg`.
+
+However, since we're not using a bundler, it's much easier and more reliable to import by converting the SVG file 
+to a .tsx file, making it a component that can be imported in our source file. For that task, we use the command-line version of SVGR.
+
+The package.json file contains a script for running SVGR properly. Running `npm run convert-assets` will process all .svg files in ./src/assets/svg into
+.tsx files located in ./src/assets. To use one of the newly-generated components, simply import as you would any component.
+
+```
+import { JogLong } from '../assets';
+
+<JogLong className="distance-selector-button" width={16} height={16} />
+```
+
+Note that hand-editing out some features out of the TSX file is often required. Because of that, the convert-assests command is set not to
+overwrite existing .tsx files. If you need to update a pre-existing .tsx file, delete it first.
+
+Possible options for SVGR:
+https://react-svgr.com/docs/options/
+
+## Documentation
+
+To generate documentation:
+```
+npm run generate-docs
+```
+
+Publishing the package will also regenerate the documentation.
+
+## Additional Documentation
+
+Beyond doc-comments in the code, we provide additional documentation in the additional-docs folder.
+
+- AutoCoreTagContext Manual: [AutoCoreTagContext Manual](../additional-docs/AutoCoreTagContext.md).
+- Button API Specs: [Button API Specs](../additional-docs/ButtonApiSpecs.md).
+- Global Event Emitter: [Global Event Emitter](../additional-docs/GlobalEventEmitter.md).
+
+## Acknowledgements
+
+Beyond the obvious, inherent React and TypeScript libraries, autocore-react greatly appreciates the works of
+these additional libraries.
+
+- PrimeReact and PrimeIcons
+- numerable
+- Simple Keyboard (https://github.com/hodgef/simple-keyboard)
+- - We customize Simple Keyboard for cleaner physical keyboard integration.
+- Monaco editor
+- socket-io
+- Tauri
+
+## Copyright
+
+(C) Copyright 2021-2025 Automated Design Corp. All Rights Reserved.
+
+## License
+
 Licensed for use on ADC equipment or within ADC software.