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.

Hub

Whether running in a browser or within a Tauri application, the user interface of a web app needs to communicate with a backed. The Hub abstracts this by defining a common base class, then automatically selecting the proper pipeline based upon the environment. If the Tauri environment is detected, HubTauri is loaded. For a browser instance, a socket.io connection is used. When running in a development environment, a simulated backend that simply echoes responses is used.

When writing the main application or developing components, you only need to focus on the Hub class. Because the backend is selected automatically, the web application does not need to be modified for each individual environment.

Installation

Install from NPM.

npm install --save @adcops/autocore-react

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 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.

• Button API Specs: Button API Specs.
• Global Event Emitter: Global Event Emitter.

Acknowledgements

Beyond the obvious, inherent React 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.

Copyright

(C) Copyright 2021-2024 Automated Design Corp. All Rights Reserved.

License

Licensed for use on ADC equipment or within ADC software.