@adcops/autocore-react 3.0.0

package/LICENSE

@@ -0,0 +1,59 @@
+ADC STANDARD SOFTWARE LICENSE AGREEMENT 
+
+This Software License Agreement ("Agreement") is made and effective on the date of delivery by and between Automated Design Corp. ("Developer") and the buyer ("Licensee"). 
+Developer has developed and licenses to users its software (the "Software") for use in operation of and data collection from Automated Design Corp products and systems. 
+
+Licensee desires to utilize a copy of the Software. 
+
+NOW, THEREFORE, in consideration of the mutual promises set forth herein, Developer and Licensee agree as follows: 
+
+1. License.
+Developer hereby grants to Licensee a perpetual, non-exclusive, limited license to use the Software in the United States of America as set forth in this Agreement. 
+
+2. Restrictions.
+Licensee shall not modify, copy, duplicate, reproduce, license or sublicense the Software, or transfer or convey the Software or any right in the Software to anyone else without the prior written consent of Developer; provided that Licensee may make one copy of the Software for backup or archival purposes. 
+
+3. Warranty of Title.
+Developer hereby represents and warrants to Licensee that Developer is the owner of the Software or otherwise has the right to grant to Licensee the rights set forth in this Agreement. In the event any breach or threatened breach of the foregoing representation and warranty, Licensee's sole remedy shall be to require Developer or to either: i) procure, at Developer's expense, the right to use the Software, ii) replace the Software or any part thereof that is in breach and replace it with Software of comparable functionality that does not cause any breach, or iii) refund to Licensee the full amount of the license fee upon the return of the Software and all copies thereof to Developer. 
+
+4. Warranty of Functionality.
+A. For a period of ONE YEAR following delivery of the Software to Licensee (the "Warranty Period"), Developer warrants that the Software shall perform in all material respects according to the Developer's specifications concerning the Software when used with the appropriate computer equipment. In the event of any breach or alleged breach of this warranty, Licensee shall promptly notify Developer and return the Software to Developer at Licensee’s expense. Licensee’s sole remedy shall be that Developer shall correct the Software so that it operates according to the warranty. This warranty shall not apply to the Software if modified by anyone or if used improperly or on an operating environment not approved by Licensor. 
+
+B. In the event of any defect in the media upon which the Software is provided arising within 1 MONTH of the date of delivery of the Software, upon return to Developer of the Software upon the original media, Developer shall provide Licensee a new copy of the Software. 
+
+5. Software Maintenance.
+A. Standard maintenance. During the Warranty Period, Developer shall provide to Licensee any new, corrected or enhanced version of the Software as created by Developer. Such enhancement shall include all modifications to the Software which increase the speed, efficiency or ease of use of the Software, but shall not include any substantially new or rewritten version of the Software. 
+
+B. Optional maintenance. After expiration of the Warranty Period, Licensee may continue to receive maintenance support for successive twelve (12) month periods. The charge for such optional maintenance support shall be Developer's regular list price for maintenance and support for the Software as published from time to time by Developer. Licensor shall notify Developer in writing if it desires to receive optional maintenance. If Licensee fails to take optional maintenance and later elects to receive it, Developer reserves the right to charge Licensee its maintenance fees for the period of the lapse in maintenance. Developer may elect to discontinue maintenance at any time upon notice to Licensee, and refund of any then unearned maintenance fees. 
+
+6. Payment.
+Payment of the license fee shall be made upon delivery of the Software, unless the payment terms of the applicable ADC proposal state otherwise. Payment of any other amount owed by Licensee to Developer pursuant to this Agreement shall be paid within thirty (30) days following invoice from Developer. In the event any overdue amount owed by Licensee is not paid following ten (10) days written notice from Developer, then in addition to any other amount due, Developer may impose and Licensee shall pay a late payment charge at the rate of one percent (1%) per month on any overdue amount.
+
+7. Taxes.
+In addition to all other amounts due hereunder, Licensee shall also pay to Developer, or reimburse Developer as appropriate, all amounts due for property tax on the Software and for sales, use, excise taxes or other taxes which are measured directly by payments made by Licensee to Developer. In no event shall Licensee be obligated to pay any tax paid on the income of Developer or paid for Developer's privilege of doing business. 
+
+8. Warranty Disclaimer.
+DEVELOPER'S WARRANTIES SET FORTH IN THIS AGREEMENT ARE EXCLUSIVE AND ARE IN LIEU OF ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
+
+9. Limitation of Liability.
+Developer shall not be responsible for, and shall not pay, any amount of incidental, consequential or other indirect damages, whether based on lost revenue or otherwise, regardless of whether Developer was advised of the possibility of such losses in advance. In no event shall Developer's liability hereunder exceed the amount of license fees paid by Licensee, regardless of whether Licensee's claim is based on contract, tort, strict liability, product liability or otherwise. 
+
+10. Notice.
+Any notice required by this Agreement or given in connection with it, shall be in writing and shall be given to the appropriate party by personal delivery or by certified mail, postage prepaid, or recognized overnight delivery services. 
+
+11. Governing Law.
+This Agreement shall be construed and enforced in accordance with the laws of the state of Illinois, USA.
+
+12. No Assignment.
+Neither this Agreement nor any interest in this Agreement may be assigned by Licensee without the prior express written approval of Developer. 
+
+13. Final Agreement.
+This Agreement terminates and supersedes all prior understandings or agreements on the subject matter hereof. This Agreement may be modified only by a further writing that is duly executed by both parties. 
+
+14. Severability.
+If any term of this Agreement is held by a court of competent jurisdiction to be invalid or unenforceable, then this Agreement, including all of the remaining terms, will remain in full force and effect as if such invalid or unenforceable term had never been included. 
+
+15. Headings.
+Headings used in this Agreement are provided for convenience only and shall not be used to construe meaning or intent. 
+
+IN WITNESS WHEREOF, Developer and Licensee have executed this Software License Agreement on the day and year first above written. 

package/additional-docs/ButtonApiSpecs.md

@@ -0,0 +1,48 @@
+# Button API
+
+## Overview
+Buttons in an HMI need to accomplish the following.
+
+- Indication of state
+- - Properties:
+- - - topic? : The name of the topic to monitor for state indicator.
+- - - onColor? : The button severity to apply when the state is TRUE. 
+- - - offColor? : The button severity to apply state is FALSE.
+- - - onLabel? : Text displayed when the state is TRUE. If null or undefined, the label property is used.
+- - - offLabel? : Text displayed when the state is FALSE. If null or undefined, the label property is used.
+- - PrimeReact severity constants should be acceptable for onColor and offColor. However, the following should also map:
+- - - "on" -> "success"
+- - - "off" -> "secondary"
+- - If topic is not undefined or null, but state is undefined or null, then the button is invalid.
+- - - Background: black Foreground: gray
+- - - This style most likely need to be created as a constant.
+- Signal (dispath) events
+- - This is more complicated because a signal has three properties:
+- - - The name of the command that must be invoked. 
+- - - The topic for that command.
+- - - An optional value. For pushbuttons, it is common for that value to be TRUE when the button is clicked or pressed and FALSE when released.
+- - - - It is also common for an invert property so that the direction of those signals are inverted.
+- - Edge cases that need more complicated handling (invoking events with additional arguments) can be handled using standard button events.
+- - HMI buttons usually support sending signals on the following input modes:
+- - - TAP : When the button is pressed down, a TRUE signal is broadcast. When released, a FALSE signal is broadcast.
+- - - - This mode is meant to simulate the behavior of an actual industrial pushbutton.
+- - - - This is, by far, the most common use case.
+- - - TOGGLE: When the button is clicked, it sends and sets its state to the inverse of its current state.
+- - - PRESSED : When the button is pressed, it signals the topic and the TRUE value, though the value is usually ignored.
+- - - RELEASED : When the button is released, it signals the topic and the FALSE value, though the value is usually ignored.
+- - - The signal values listed here would be inverted if the inverted property is true.
+- - While theoretically possible that a button have need to support both a tap and toggle, or pressed/relesaed, these are extreme edge cases.
+- - - Therefore, instead of creating a massive number of properties, we shall create an inputMode property.
+- - Properties
+- - - inputMode: Tap, Toggle, pressed, released
+- - - command: name of the command to invoke
+- - - commandArgs: Arguments sent with the command. Usually this will be an object containing the topic name and the value.
+- - - disableTopic : A topic the button can monitor to disable dispatching signals on events. 
+- - - invisbleTopic : A topic the button can monitor to hide its visibility.
+- Because buttons are such a common function, we will extend the PrimeReact Button class to have these features.
+- These features are commonly needed, so we will also make a HOC function to add these properties and functions to an existing component.
+- Input mode should be enumerated. 
+- The buttons should default to being "raised," which is a standard attribute of PrimeReact buttons.
+
+
+

package/additional-docs/GlobalEventEmitter.md

@@ -0,0 +1,244 @@
+
+
+This is a quick example that needs to be updated. Stay tuned.
+
+
+## Wrap the application in the EventEmitterContext
+
+```
+
+// App.js or App.tsx
+
+import React from 'react';
+import { EventEmitterProvider } from "autocore-react/core/EventEmitterContext.js";
+import ContentView from 'path-to/ContentView';
+
+const App = () => {
+  return (
+    <EventEmitterProvider>
+      <ContentView />
+      {/* Other components */}
+    </EventEmitterProvider>
+  );
+};
+
+export default App;
+
+```
+
+
+## Subscribing in a component
+
+```
+import React, { useState, useEffect, useContext } from 'react';
+import { Button } from "primereact/button";
+import { ValueDisplay } from 'autocore-react/components/ValueDisplay';
+import { Indicator, IndicatorGreen, IndicatorOff } from "autocore-react/components/Indicator";
+import { EventEmitterContext } from '../path/to/EventEmitterContext'; // Adjust the import path as necessary
+
+export const ContentView: React.FC = () => {
+    const [count, setCount] = useState(0);
+    const [blink, setBlink] = useState(false);
+    const [controlPower, setControlPower] = useState<number | string | null | undefined>(0);
+    const { subscribe } = useContext(EventEmitterContext);
+
+    useEffect(() => {
+        console.log("Setting up interval.");
+
+        const intervalId = setInterval(() => {
+            console.log("blink");
+            setBlink(blink => !blink);
+        }, 1000);
+
+        // Subscribe to the 'there-is-no-spoon' topic
+        const unsubscribe = subscribe('there-is-no-spoon', (value) => {
+            setControlPower(value);
+        });
+
+        return () => {
+            console.log("Cleaning up.");
+            clearInterval(intervalId);
+            unsubscribe(); // Unsubscribe when the component unmounts
+        }
+    }, [subscribe]);
+
+    const incrementCount = () => {
+        setCount(count + 1);
+    };
+
+    return (
+        <div>
+            <p>{count}</p>
+            <Button onClick={incrementCount}>Increment</Button>
+            <br />
+            <div>
+                Maximum Power: <ValueDisplay value={0.34} x={200} y={320} width={100} height={20} format="0%"></ValueDisplay>
+            </div>
+            <div>
+                Control Power: <Indicator value={blink} onColor={IndicatorGreen} offColor={IndicatorOff} />
+            </div>
+            <div>
+                Received Power: <ValueDisplay value={controlPower} x={200} y={350} width={100} height={20} format="0%"></ValueDisplay>
+            </div>
+        </div>
+    );
+};
+```
+
+
+
+
+## Publishing a value from Typescript.
+
+This is a shit example. Usually, use the Hub singleton. However, this example displays the concept.
+
+Implement a publisher function. 
+
+```
+// EventPublisher.ts
+import React, { useContext } from 'react';
+import { EventEmitterContext } from '../path/to/EventEmitterContext'; // Adjust the import path as necessary
+
+export const publishToThereIsNoSpoon = (topic: string, payload: any) => {
+    const { dispatch } = useContext(EventEmitterContext);
+
+    dispatch({
+        topic: topic,
+        payload: payload,
+    });
+};
+
+```
+
+Publish from a component:
+
+```
+import React from 'react';
+import { publishToThereIsNoSpoon } from './EventPublisher';
+
+const SomeComponent: React.FC = () => {
+    const handleClick = () => {
+        // Publish an event with some payload
+        publishToThereIsNoSpoon("New Value");
+    };
+
+    return (
+        <button onClick={handleClick}>Publish Event</button>
+    );
+};
+
+export default SomeComponent;
+
+
+```
+
+
+
+
+
+
+
+### Component Example:
+```
+
+import React, { useState, useEffect, useContext } from 'react';
+import { Button } from "primereact/button";
+import { ValueDisplay } from 'autocore-react/components/ValueDisplay';
+import { Indicator, IndicatorGreen, IndicatorOff } from "autocore-react/components/Indicator";
+import {EventEmitterContext} from "autocore-react/core/EventEmitterContext";
+import {ValueSimulator} from "autocore-react/core/ValueSimulator";
+
+
+
+export const ContentView: React.FC = () => {
+    const [count, setCount] = useState(0);
+    const [blink, setBlink] = useState(false);
+    const [controlPower, setControlPower] = useState(false);
+    const {dispatch, subscribe, unsubscribe} = useContext(EventEmitterContext);
+
+    const simulator = new ValueSimulator(dispatch);
+
+
+    useEffect(() => {
+
+        simulator.start();
+
+
+        // Subscribe to the 'there-is-no-spoon' topic
+        // TODO: add an unsubscribe feature
+        const unsubscribeControlPower = subscribe('value-simulator-bBit1', (value) => {
+            console.log(`value-simulator-bBit1: ${value}`);
+            setControlPower(value);
+        });        
+
+        const unsubscribeBlink = subscribe('value-simulator-bBit2', (value) => {
+            console.log(`value-simulator-bBit2: ${value}`);
+            setBlink(value);
+        });        
+
+
+        const unsubscribePower = subscribe('value-simulator-iRamp1', (value) => {
+            console.log(`value-simulator-iRamp1: ${value}`);
+            setCount(value);
+        });        
+
+
+        // console.log(`IntervalID: ${intervalId}`);
+
+        return () => {
+            unsubscribe(unsubscribeControlPower);
+            unsubscribe(unsubscribeBlink);
+            unsubscribe(unsubscribePower);
+            simulator.stop();
+        }
+    }, [] );
+
+    const incrementCount = () => {
+        setCount(count + 1);
+    };
+
+    
+
+    return (
+        <div>
+            <p>{count}</p>
+            <Button onClick={incrementCount}>Increment</Button>
+            <br />
+            <div>
+                Maximum Power: <ValueDisplay value={count / 100} x={200} y={320} width={100} height={20} format="0%"></ValueDisplay>
+            </div>
+            <div>
+                Control Power: <Indicator value={controlPower}></Indicator>
+            </div>            
+            <div>
+                Blink: <Indicator value={blink} onColor={IndicatorGreen} offColor={IndicatorOff} />
+            </div>
+
+        </div>
+
+    );
+};
+
+
+```
+
+
+
+
+# Higher Order Component Subscription
+
+As it is infeasible for autocore-react to modify every possible component to streamline subscription
+and dispatching capabilities, we add Higher Order Component (HOC) functions to easily adapt a generic
+component into one that can subscribe to events and values.
+
+
+// For a component expecting 'value' prop
+```
+
+const SubscribedValueDisplay = hocAddSubscription(ValueDisplay, 'some-topic', 'value');
+```
+
+And use it in your component:
+```
+<SubscribedValueDisplay x={200} y={320} width={100} height={20} format="0%" />
+``````

package/additional-docs/general_recommendations.md

@@ -0,0 +1,22 @@
+# General Recommendations
+
+These recommendations will help you skip over all the pitfalls we've already worked through.
+
+## Accepting Input
+
+PrimeReact/InputGroup makes it easy to group a label, input field, units and button into the same contiguous "block." In general,
+the user is best served by using InputGroup when accepting user input. Trying to put a similar effect together with a custom layout or CSS
+tends to be a waste of time and effort.
+
+See examples here: [InputGroup](https://primereact.org/inputgroup/ "https://primereact.org/inputgroup/")
+
+### Numeric input
+
+Use PrimeReact/InputNumber to filter numeric input as needed. If you need to filter programatically or the InputNumber field simply
+won't work for your application, core/MaskPatterns/RegExMaskPatterns enumerates regular expression constants that can be used
+to filter/validate input.
+
+### Masking other inputs
+
+Use PrimeReact/InputMask to filter other data as needed. We provide core/MaskPatterns/PrimeReactMaskPatterns for some common
+masks.