@adcops/autocore-react 3.0.0

package/src/core/EventEmitterContext.tsx

@@ -0,0 +1,394 @@
+/*
+ * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
+ * Created Date: 2024-01-17 11:45:10
+ * -----
+ * Last Modified: 2024-03-08 10:20:46
+ * Modified By: ADC
+ * -----
+ * 
+ */
+
+
+import React, { createContext, ReactNode, useState, useMemo } from 'react';
+import {createHub, Hub} from "../hub";
+
+export {Hub};
+
+/**
+ * Represents an event subsription.
+ */
+export interface Subscription {
+    /** ID of the subscription used for unsubscription. */
+    id: number;
+    /** Callback function. */
+    callback: React.Dispatch<any>;
+}
+
+
+/**
+ * Represents the payload data associated with an event.
+ */
+export interface State {
+    /**
+     * The optional data payload of the event.
+     */
+    eventData?: any;
+    /** Callback subscription. A list of callback subscriptions matched to a topic. */
+    subscriptions: Record<string, Subscription[]>;
+
+    /** Tracks the next subscription ID that will be assigned. */
+    nextSubscriptionId: number; 
+}
+
+/**
+ * An action event published by the EventEmitterContext. Contains
+ * the topic identifying the event and the optional payload, which is
+ * a value of any type.
+ */
+export interface Action {
+
+    /**
+     * The topic or identifier of the event.
+     */
+    topic: string;
+
+    /**
+     * The optional data payload associated with the event.
+     */
+    payload?: any;
+}
+
+/** 
+ * Type declaration for the EventEmitter dispatch function, which
+ * publishes an Action globally throughout the EventEmitterContext.
+ */
+export type EmitterDispatchFunction = (action: Action) => void;
+
+/** 
+ * Type declaration for the EventEmitter dispatch function, which
+ * receives an Action on a specific topic broadcast through the EventEmitterContext.
+ */
+export type EmitterSubscribeFunction = (action: Action) => void;
+
+/** 
+ * Type declaration for the EventEmitter unsubscribe function, which
+ * receives an Action on a specific topic broadcast through the EventEmitterContext.
+ */
+export type EmitterUnsubscribeFunction = (action: Action) => void;
+
+
+/**
+ * Defines the context for an event emitter used throughout a front-end application to manage and dispatch events.
+ * This interface includes methods for managing the application's state, handling global actions, communicating with the back end,
+ * subscribing to and unsubscribing from events, and accessing a global hub for event publishing and subscription management.
+ * It serves as a central point for event-driven interactions within the application, facilitating communication between
+ * components and the back end, as well as among components themselves.
+ */
+export interface EventEmitterContextType {
+    /**
+     * The current state of the event emitter, containing the latest event data.
+     */
+    state: State;
+
+    /**
+     * A function to dispatch actions globally throughout the front-end, 
+     * triggering state updates and events.
+     *
+     * @param action The action to dispatch, containing topic and optional payload.
+     */
+    dispatch: (action: Action) => void;
+
+
+    /** 
+     * Invoke/send a message to the back end. 
+     * This does NOT get published to the front end.
+     */
+    invoke(fname: string, payload? : object) : Promise<object>;
+
+    /**
+     * Subscribe to events identified by the topic.
+     * @param topic The subscription topic.
+     * @param callback The callback to signal.
+     * @returns number Subscription ID used to unsubscribe later.
+     */
+    subscribe: (topic: string, callback: React.Dispatch<any>) => number;
+
+    /**
+     * Unsubscribe to events.
+     * @param subscriptionId The id of the subscription returned by the subscribe method.
+     * @returns 
+     */
+    unsubscribe: (subscriptionId : number) => void;    
+
+
+    /**
+     * Global hub for publishing and receiving events throughout the interface, and for exchanging
+     * data with the backend.
+     */
+    hub : Hub | null;
+
+    /**
+     * Retrieves the current subscriptions. Used for debugging purposes.
+     * @param topic Optional. The topic to retrieve subscriptions for. If omitted, returns all subscriptions.
+     * @returns An object containing the current subscriptions, optionally filtered by topic.
+     */
+    getSubscriptions: (topic?: string) => Record<string, Subscription[]> | Subscription[];    
+}
+
+/**
+ * A global context for managing event emission and subscription.
+ *
+ * Creates a React context for the EventEmitter system, providing a structured way to manage events and data flow
+ * in a React application. It serves as a global event bus that components can subscribe to or emit events, allowing for
+ * a loosely coupled architecture. Additionally, it provides a mechanism for invoking backend functions and managing
+ * subscriptions, making it easier to integrate React components with backend services.
+ * 
+ * The context includes several key functionalities:
+ * - `state`: Maintains the current state of subscriptions and their identifiers.
+ * - `dispatch`: Allows components to emit events with specific topics and payloads, which can be listened to by other components.
+ * - `subscribe`: Enables components to listen to specific topics and react to those events by providing a callback function.
+ * - `unsubscribe`: Provides a way for components to stop listening to events, helping prevent memory leaks and unnecessary updates.
+ * - `invoke`: Facilitates calling backend functions with specific arguments and handling their responses asynchronously.
+ * - `getSubscriptions`: Offers insight into current active subscriptions, useful for debugging purposes.
+ * 
+ * This context is essential for applications that require a high degree of inter-component communication or need to
+ * interact with a backend efficiently.
+ * 
+ * For more information, see [Additional Documentation](../additional-docs/GlobalEventEmitter.md).
+ * 
+ * ## Usage
+ * 
+ * The entire application should be wrapped in the EventEmitterProvider.
+ * 
+ * App.tsx
+ * ```
+ * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
+ * function App() {
+ * 
+ *      return(
+ *          <EventEmitterProvider>
+ *              <PrimeReactProvider>
+ *                  <main>
+ *                      <section>
+ *                          <ContentView />
+ *                      </section>
+ *                  </main>
+ *              </PrimeReactProvider>
+ *          </EventEmitterProvider>
+ *      );
+ * 
+ * }
+ * 
+ * ```
+ * 
+ * ### Catching and receiving events
+ * The EventEmitterContext creates an appropriate instance of the hub, which is derived from HubBase.
+ * That hub can be used to publish and subscribe to
+ * topics globally in the front-end, regardless of being connected to any backend.
+ * Usage within a component is simple.
+ * 
+ * ```
+ * const {dispatch, subscribe, unsubscribe} = useContext(EventEmitterContext);
+ * const [controlPower, setControlPower] = useState(false);
+ * useEffect(() => {
+ *      const unsubscribeControlPower = subscribe('value-simulator-bBit1', (value) => {
+ *          setControlPower(value);
+ *      });  
+ *
+ *
+ *      return () => {
+ *           unsubscribe(unsubscribeControlPower);
+ *      }
+ * }, [] );
+ * 
+ * const onPbPressed = () => {
+ *      let count = 1;
+ *      dispatch({
+ *          topic: "my-awesome-topic",
+ *          payload: count
+ *      });
+ * }
+ * 
+ * ``` 
+ * The hub should also be used for invoking events in the backend.
+ * This example will call the function "update_count" in the backend, passing
+ * the expected argument "count". Details of the interaction between the Hub and
+ * the backend will be handled by the appropriate HubBase sub-class, and should
+ * be transparent to the front end.
+ * 
+ * ```
+ * const {invoke} = useContext(EventEmitterContext);
+ * const incrementCount = () => {
+ *    count += 1;
+ *    invoke('update_count', {"count": count});        
+ * };
+ * 
+ * Subscribing to a topic is simple. The type of value received is specific
+ * to the topic.
+ * 
+ * Example: Listen to an event 'xarm-position':
+ * ```
+ * const {subscribe, unsubscribe} = useContext(EventEmitterContext);
+ * useEffect(() => {
+ *         const unsubscripeMp = subscribe('xarm-position', (value) => {
+ *            // The publisher sent a JSON object of 3D position values. 
+ *            setX(value.x);
+ *            setY(value.y);
+ *            setZ(value.z);
+ *            setA(value.roll);
+ *            setB(value.yaw);
+ *            setC(value.pitch);
+ *        });
+ * 
+ *    return () => {
+ *        unsubscribe(unsubscripeMp);
+ *    }
+ * 
+ * }, [] );
+ *
+ * ```
+ * 
+ * For applications that need to access the instance of the hub, get the current instance
+ * from the EventEmitterContext:
+ * 
+ * ```
+ * const {hub} = useContext(EventEmitterContext);
+ *  * ```
+ * 
+ * 
+ */
+export const EventEmitterContext = createContext<EventEmitterContextType>({
+    state: { subscriptions: {}, nextSubscriptionId : 1 },
+    dispatch: () => { },
+    subscribe: () => { return 0; }, // Placeholder for subscription logic
+    invoke: async (fname: string, payload?: object) => { 
+        fname;
+        payload;
+        // Placeholder for invoke logic
+        // Implement the logic to send a message to the backend and return a promise
+        return Promise.resolve({}); // Example placeholder, replace with actual implementation
+    },
+    unsubscribe: (subscriptionId: number) => { subscriptionId;}, // Placeholder for unsubscription logic    
+    hub: null,
+    getSubscriptions: () => { return []; } 
+});
+
+
+/**
+ * A React component that provides the EventEmitterContext to its children.
+ *
+ * Wraps child components with the context, enabling them to access and interact
+ * with the event emitter.
+ *
+ * @param children The child components to be wrapped in the context.
+ * 
+ * ## Usage
+ * 
+ * The entire application should be wrapped in the EventEmitterProvider.
+ * 
+ * App.tsx
+ * ```
+ * import { EventEmitterProvider } from "@adcops/autocore-react/core/EventEmitterContext.js";
+ * function App() {
+ * 
+ *      return(
+ *          <EventEmitterProvider>
+ *              <PrimeReactProvider>
+ *                  <main>
+ *                      <section>
+ *                          <ContentView />
+ *                      </section>
+ *                  </main>
+ *              </PrimeReactProvider>
+ *          </EventEmitterProvider>
+ *      );
+ * 
+ * }
+ * 
+ * ``` 
+ */
+export const EventEmitterProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
+    const [state, setState] = useState<State>({ subscriptions: {}, nextSubscriptionId : 1 });
+
+    // Memoize the hub instance so it's only created once
+    const hub = useMemo(() => createHub(), []);
+
+    const dispatch = (action: Action) => {
+        const { topic, payload } = action;
+
+        setState(prevState => {
+            prevState.subscriptions[topic]?.forEach(sub => sub.callback(payload));
+            return { ...prevState, eventData: payload };
+          });
+    };
+
+    const subscribe = (topic: string, callback: React.Dispatch<any>) : number => {
+
+        const subscriptionId = state.nextSubscriptionId;
+
+        setState(prevState => ({
+            ...prevState,
+            subscriptions: {
+              ...prevState.subscriptions,
+              [topic]: [...(prevState.subscriptions[topic] || []), { id: subscriptionId, callback }]
+            },
+            nextSubscriptionId: prevState.nextSubscriptionId + 1
+          }));
+        
+          return subscriptionId;
+    };
+
+
+    const unsubscribe = (subscriptionId: number) => {
+        setState(prevState => {
+            const newSubscriptions = { ...prevState.subscriptions };
+    
+            // Iterate through all topics
+            for (const topic in newSubscriptions) {
+                if (newSubscriptions.hasOwnProperty(topic)) {
+                    // Filter out the subscription with the given ID
+                    newSubscriptions[topic] = newSubscriptions[topic].filter(sub => sub.id !== subscriptionId);
+    
+                    // If the topic now has no subscriptions, you can optionally delete the topic key
+                    if (newSubscriptions[topic].length === 0) {
+                        delete newSubscriptions[topic];
+                    }
+                }
+            }
+    
+            return { ...prevState, subscriptions: newSubscriptions };
+        });
+    };
+
+
+    const getSubscriptions = (topic?: string): Record<string, Subscription[]> | Subscription[] => {
+        if (topic) {
+            // Return subscriptions for the provided topic, or an empty array if the topic doesn't exist
+            return state.subscriptions[topic] || [];
+        } else {
+            // Return all subscriptions
+            return state.subscriptions;
+        }
+    };    
+
+    // Provide the memoized hub instance in the context value
+    const contextValue = useMemo(() => ({
+        state, 
+        dispatch, 
+        subscribe, 
+        unsubscribe, 
+        invoke: hub.invoke,
+        hub,
+        getSubscriptions
+    }), [state, hub]);    
+
+
+    hub.setContext(contextValue);
+
+    return (
+        <EventEmitterContext.Provider value={contextValue}>
+            {children}
+        </EventEmitterContext.Provider>
+    );
+
+};

package/src/core/MaskPatterns.ts

@@ -0,0 +1,82 @@
+/*
+ * (C) Copyright 2021 Automated Design Corp. All Rights Reserved.
+ * File Created: Thursday, 1st April 2021 12:30:41 pm
+ * Author: Thomas C. Bitsky Jr. Automated Design Corp.
+ */
+
+/**
+ * @fileoverview
+ * Provides a collection of pre-defined patterns for masking/validating different types of user input or data string. 
+ * These patterns come up so regularly in our work that it seemed best to standardize and centralize their definition.
+ * 
+ * These patterns can be used to ensure that user inputs conform to expected formats, such as real numbers (with or without
+ * decimal points), positive real numbers, integers, and positive integers. Utilizing these patterns simplifies the process
+ * of validating and filtering input in forms or any other user input scenarios.
+ *
+ * The patterns are defined as regular expressions and are encapsulated within the `InputPatterns` constant for easy access.
+ * They can be used directly with input validation functions or in conjunction with form validation libraries to enforce
+ * input constraints.
+ */
+
+/**
+ * Regular expressions Common input patterns for matching different input or expected data types.
+ */
+export const RegExMaskPatterns = {
+    /**
+     * Regular expression pattern for matching real numbers.
+     * This pattern matches any real number, including negative and positive numbers with or without a decimal point.
+     * Examples of valid inputs: "123", "-123", "123.456", "-123.456", ".456", "-.456"
+     */    
+    RealNumber: /^-?\d*(\.)?(\d+)?$/,
+    /**
+     * Regular expression pattern for matching positive real numbers.
+     * This pattern matches any positive real number with or without a decimal point, excluding negative numbers.
+     * Examples of valid inputs: "123", "123.456", ".456"
+     */    
+    RealNumberPositive: /^\d*(\.)?(\d+)?$/,
+    /**
+     * Regular expression pattern for matching integers.
+     * This pattern matches any integer, including negative and positive integers without a decimal point.
+     * Examples of valid inputs: "123", "-123"
+     */    
+    Integer: /^-?\d*$/,
+    /**
+     * Regular expression pattern for matching positive integers.
+     * This pattern matches any positive integer without a decimal point, excluding negative numbers.
+     * Examples of valid inputs: "123"
+     */    
+    IntegerPositive: /^\d+$/
+} as const;
+
+
+
+/**
+ * Patterns for use with PrimeReact.InputMask components
+ */
+export const PrimeReactMaskPatterns = {
+    /** USA Social Security Number */
+    SocialSecurityNumber: "999-99-9999",
+    /** USA phone number with optional extension */
+    PhoneNumberUS: "(999) 999-9999? x99999",
+    /** International phone number with optional extension */
+    PhoneNumberInternational: "+999 999 999 9999? x99999",
+    /** International phone number with optional extension */
+    PhoneNumberJapan: "+81 9999 999 9999? x99999",
+    /** International phone number with optional extension */
+    PhoneNumberChina: "+86 999 999 9999? x99999",
+    /** International phone number with optional extension */
+    PhoneNumberVietnam: "+84 999 999 9999? x99999",
+    /** International phone number with optional extension */
+    PhoneNumberSouthKorea: "+82 99 9999 9999 x99999",
+    /** International phone number with optional extension */
+    PhoneNumberCanada: "+1 (999) 999-9999 x99999",
+    /** International phone number with optional extension */
+    PhoneNumberMexico: "+52 999 999 9999 x99999",    
+    /** International phone number with optional extension */
+    PhoneNumberScotland: "+44 9999 999999 x99999",        
+    /** International phone number with optional extension */
+    PhoneNumberEngland: "+44 9999 999999 x99999",        
+    /** International phone number with optional extension */
+    PhoneNumberIreland: "+353 99 999 9999 x99999",        
+
+} as const;

package/src/core/NumerableTypes.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
+ * Created Date: 2024-01-16 14:19:17
+ * -----
+ * Last Modified: 2024-03-08 07:55:25
+ * Modified By: ADC
+ * -----
+ * 
+ */
+
+/**
+ * @fileoverview
+ * 
+ * These types enhance TypeScript support for the `numerable` library, which does not directly
+ * export the `NumerableFormatNumberOptions` type. By extracting and refining the type definitions
+ * for the `format` function's parameters, including handling its overloaded signatures, this file
+ * makes it easier to use `numerable` in TypeScript and React projects.
+ * 
+ * The process involves creating a type that captures the overloads of the `format` function and
+ * then mapping over these overloads to extract their parameters. This technique enables the
+ * extraction of the specific options type `NumerableFormatNumberOptions` used by the `format`
+ * function, thereby providing type safety and IntelliSense support in TypeScript environments.
+ * 
+ * The approach used here is based on a solution for handling function overloads in TypeScript,
+ * as discussed in a StackOverflow answer: https://stackoverflow.com/a/59538756/10049787.
+ */
+
+import { format } from 'numerable';
+
+/**
+ * Type helper to capture the overload signatures of a function.
+ * This utility type takes a function with multiple overloads and maps them to a tuple of
+ * functions, each representing one of the overloads.
+ */
+type NumerableFormatOverloads<T> = T extends {
+  (...args: infer A1): infer R1;
+  (...args: infer A2): infer R2;
+  (...args: infer A3): infer R3;
+}
+  ? [(...args: A1) => R1, (...args: A2) => R2, (...args: A3) => R3]
+  : T extends {
+      (...args: infer A1): infer R1;
+      (...args: infer A2): infer R2;
+    }
+  ? [(...args: A1) => R1, (...args: A2) => R2]
+  : T extends {
+      (...args: infer A1): infer R1;
+    }
+  ? [(...args: A1) => R1]
+  : any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/**
+ * Extracts parameters from a tuple of function types.
+ * This utility type maps over a tuple of functions (representing overloads) to produce a tuple
+ * of their respective parameter types.
+ */
+type OverloadedParameters<T> = NumerableFormatOverloads<T> extends infer O
+  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    { [K in keyof O]: Parameters<Extract<O[K], (...args: any) => any>> }
+  : never;
+
+/**
+ * Type representing the parameters of the `numerable.format` function, taking into account its
+ * overloaded signatures.
+ */  
+type NumerableFormatParams = OverloadedParameters<typeof format>;
+
+
+/**
+ * Type specifically for the options parameter of the `numerable.format` function.
+ * This extracts the type of the third parameter (options) from the first overload of `format`,
+ * as this is where the formatting options are specified.
+ */
+type NumerableFormatNumberOptions = NumerableFormatParams[0][2];
+
+/**
+ * Exported type for external use, providing a non-nullable version of the formatting options.
+ * This type is intended for use wherever `numerable.format` options are needed, enhancing
+ * code readability and type safety.
+ */
+export type NumerableFormatOptions = NonNullable<NumerableFormatNumberOptions>;

package/src/core/PositionContext.ts

@@ -0,0 +1,60 @@
+/*
+ * Copyright (C) 2024 Automated Design Corp. All Rights Reserved.
+ * Created Date: 2024-01-16 14:19:52
+  * -----
+ * Last Modified: 2024-03-08 07:48:18
+ * Modified By: ADC
+ * -----
+ * 
+ */
+
+
+
+import { createContext } from 'react';
+
+
+/**
+ * Interface representing the position and scale context of a component within its parent container.
+ * 
+ * This context is designed to provide components with necessary scaling and positioning
+ * information, such as for rendering elements correctly in absolute positioning or for
+ * adjusting layout based on dynamic offsets.
+ */
+export interface IPositionContext {
+
+  /**
+   * Represents the scale factor applied to the dimensions of elements.
+   * A scale of 1 indicates no scaling, while values greater or less than 1
+   * indicate zoomed-in or zoomed-out states respectively.
+   */    
+  scale: number;
+  /**
+   * Represents the horizontal offset that should be applied to the position
+   * of elements. This can be used to adjust element positioning in response to
+   * dynamic layout changes or to align elements within a scaled environment.
+   */  
+  xOffset: number;
+  /**
+   * Represents the vertical offset that should be applied to the position
+   * of elements. Similar to `xOffset`, this is used for vertical alignment and
+   * positioning adjustments in a dynamic or scaled layout.
+   */  
+  yOffset: number;
+}
+
+
+/**
+ * Creates a React context for position and scaling information of a component using absolute positioning.
+ * This context provides a standardized way to access and react to changes in scale and positioning offsets,
+ * enabling components to adjust their layout and rendering behavior dynamically.
+ *
+ * The default context values are set to assume no scaling (`scale: 1`) and no offsets (`xOffset: 0, yOffset: 0`),
+ * which corresponds to the initial state in many applications before any dynamic adjustments are made.
+ */
+export const DimensionsContext = createContext<IPositionContext>({
+  scale: 1, /** Default scaling factor indicating no scaling. */
+  xOffset: 0, /** Default horizontal offset indicating no shift. */
+  yOffset: 0, /** Default vertical offset indicating no shift. */
+});
+
+export default DimensionsContext;

package/src/core/UniqueId.ts

@@ -0,0 +1,41 @@
+  
+
+
+/**
+ * Generate a unique UUID in the form of RF4122.
+ * @returns string 
+ */
+const PrivateUniqueId = (function() 
+{
+    function chr4()
+    {
+        return Math.random().toString(16).slice(-4);
+    }
+
+    return chr4() + chr4() +
+        '-' + chr4() +
+        '-' + chr4() +
+        '-' + chr4() +
+        '-' + chr4() + chr4() + chr4();
+});
+
+
+/**
+ * Generates a unique UUID per RFC4122.
+ * 8 chars, followed by 3 groups of 4 chars, followed by 12 chars.
+ *
+ * @returns string UUID
+ * 
+ * ## Remarks 
+ * NOTE: This format of 8 chars, followed by 3 groups of 4 chars, followed by 12 chars
+ *       is known as a UUID and is defined in RFC4122 and is a standard for generating unique IDs.
+ *       This function DOES NOT implement this standard. It simply outputs a string
+ *       that looks similar. The standard is found here: https://www.ietf.org/rfc/rfc4122.txt
+ *
+ * Should avoid duplicates over 10-millions subsequent calls.
+ *
+ */
+export function UniqueId() : string {
+    return PrivateUniqueId();
+}
+