# React Rapid Workplace (react-rwp)
React Rapid Workplace (react-rwp) is a fully-featured web client leveraging the new [iWebServices V5 (iWS5) API](https://github.com/Greenfield-Investments/iWS5/) and the [Syncfusion React PDF Viewer](https://www.syncfusion.com/react-components/react-pdf-viewer) plugin to enable the selection and modification of Process Director work items and documents contained within. It is intended to replace both the existing iDesktop application (Intellectus fat client) and the Angular-based [LPNU-Frontend](https://github.com/Greenfield-Investments/LPNU-Frontend).

## Frameworks & Technologies
React Rapid Workplace is built using [React](https://react.dev/) (version 19.x) for runtime, the [Vite](https://vite.dev/) build tool for bundling, and the [React Bootstrap](https://react-bootstrap.netlify.app/) component library, in addition to a number of other libraries for added functionality.

To accomplish the scan insert and complex image cleanup operations available in the existing iDesktop application, the [RWP Companion](https://github.com/Greenfield-Investments/rwp-companion) application integrates with React Rapid Workplace via a WebSocket connection. The companion application must be installed on users' local machines (running Windows) and running before scan inserts or image cleanup operations can be performed. More information can be found in the companion application repository's README.

## Project Structure
There are a few choices about the project's structure worth noting:
1. API functionality is exposed through a set of types and wrapper functions mimicking iWS5 schemas and endpoints, defined in the [src/api](src/api) directory and organized by category. This is opposed to the use of Entity Framework schemas, although it shouldn't be difficult to convert the type definitions down the line. The wrapper functions use the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) to make API calls and return formatted data.
2. UI components in the [src/components](src/components) directory are organized by the level at which they're used. For example: [DataTable](src/components/DataTable.tsx) is located in the root of the components directory, as it can be used throughout the application, but [FolderTree](src/components/Processing/DetailsFolderPanel/sections/FolderSection/FolderTree.tsx) is located deep within the [Processing](src/components/Processing) component directory as it is only used there. Components shared by other components are located in the [shared](src/components/shared) directory.
3. A number of contexts exist to provide shared access to important state variables throughout the application, particularly in the Processing view. In particular, [WorkItemContext](src/contexts/WorkItemContext.tsx), [DocumentContext](src/contexts/DocumentContext.tsx), and [ProcessingUIContext](src/contexts/ProcessingUIContext.tsx) are only used in the Processing view.

## Environment Variables & Licensing
An [.env.template](.env.template) file is included in the project repository and includes all the environment variable names which must be set to develop and build the application. `.env.development` is used for development, and `.env.production` is used for production. All environment variables which should be accessible to Vite must begin with the `VITE_` prefix.

In particular, the following undefined variables in [.env.template](.env.template) must be defined before the application can be built:
```dotenv
# Local directory containing brand image files ("logo.png", "icon.png", and "favicon.ico")
VITE_APP_BRAND_IMAGE_SOURCE_DIR=

# iWS5 API URL (i.e., https://localhost:7290 for development)
VITE_API_URL=
```
Additionally, a valid license key for Syncfusion Essential Studio must be provided in the form of a `syncfusion-license.txt` file in the project root. Simply paste the license key into the file, then run:
```shell
npx syncfusion-license activate
```

The version string displayed on the login page is generated from Git repository information in the format `{COMMIT_DATE}.{REPOSITORY_NAME}.{BRANCH_NAME}+{COMMIT_ID}`. In the event that Git repository information is unavailable, the format is `{CURRENT_DATE}.{REPOSITORY_NAME}`.

## Language Support & Localization
Although React Rapid Workplace is designed in and intended for use with the English language, localization is supported through the [react-i18next internationalization framework](https://react.i18next.com/). Translations for all user interface text, including visible status messages (successes, warnings, and errors), can be provided via special `translation.json` files in the [src/i18next](src/i18next) directory.

The default [en/translation.json](src/i18next/en/translation.json) contains all the English text used throughout the application's interface, in the structure expected by each page and component. To localize for an additional language, the English translation file can be copied to a new directory within [src/i18next](src/i18next) using the language's [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes#Table) as the directory name. Then, simply translate all the JSON values to the new language, and register the language in the [i18next config file](src/i18next/config.ts):

```javascript
// Modify the supportedLanguages array
// Includes the language code, flag emoji, and display name
export const supportedLanguages: SupportedLanguage[] = [
  {
    code: 'en',
    flagEmoji: '🇺🇸',
    displayName: 'English',
  },
];

// Adjust the i18next configuration
i18next
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    // Translation resources
    resources: {
      en: {
        translation: en, // Import JSON file as country code
      },
    },
  });
```

## Post-Build Configuration
To support the configuration of certain application variables after the application is built and bundled, a special `config.js` file is generated by the [build-config-file.ts](build-config-file.ts) prebuild script and placed in the [public](/public) directory. This configuration file sets the global `window.__APP_CONFIG__` property, which is then read by the application where environment variables would otherwise be used directly.

```javascript
// Auto-generated from .env
window.__APP_CONFIG__ = {
  "COMPANY_NAME": "",
  "IWS5_API_URL": "",
  "ENABLE_RWP_COMPANION": "", // "true" enables the RWP Companion, all other values equal false
  "ENABLE_LPNU_WORK_ITEM_SIGNAGE": "", // "true" enables LPNU work item signage, all other values equal false
  "LPNU_WORK_ITEM_SIGNAGE_CERTIFICATE_ISSUERS": async () => {
    try {
      // Customizable logic that must return an array of strings
      return [`ISSUER 1`, `ISSUER 2`, `ISSUER 3`];
    } catch {
      return [];
    }
  },
};
```

The values in `config.js` can be modified after deployment without rebuilding the application, and changes are reflected as soon as users' browser cache is invalidated. String values within double quotes are used to maintain a consistent format that can be targeted for text replacement by [React Rapid Workplace's setup package](https://github.com/Greenfield-Investments/setup-packages/tree/main/react-rwp), except for the `LPNU_WORK_ITEM_SIGNAGE_CERTIFICATE_ISSUERS` property which is a function which must return an array of strings. That function can support any valid JavaScript, meaning external resources can be read at runtime to retrieve the list of valid signage certificate issuers.

Additionally, the brand images ([icon.png](/src/assets/brand/icon.png), [logo.png](/src/assets/brand/logo.png), and [favicon.ico](/public/favicon.ico)) are exempt from Vite's cache-busting feature for static assets, which normally appends random strings to the end of file names so that users' browsers detect changes sooner ([more information](https://vite.dev/guide/assets)). This allows the images to be replaced more easily after deployment.

## Development Server
To develop React Rapid Workplace, the Vite build tool can be used to run a web server on port `5173`. This development server supports automatic refreshing when changes are detected to source files.

To run the development server, complete the following steps:
1. Install packages with `npm install`.
2. Run `npm run dev`.

## Deployment
To deploy React Rapid Workplace, the Vite build tool can be used to bundle and minify the application source:
1. Install packages with `npm install`.
2. Build the application package with `npm run build`.
3. Copy the contents of the newly-generated `dist` directory to a production-ready web server.

Additionally, the production-ready version of the application can be previewed using Vite by running `npm run preview`.

**Note:** When deploying the built application to an IIS web server, a special [web.config](public/web.config) file is required for client-side routing to work as expected. This configuration file uses URL rewrites to map all requests to [index.html](index.html).