interpreaction

Spark an interReaction!

interReaction is a library which enables you to easily use React components in a non-React client application (Angular, GWT, jQuery, vanilla JavaScript, et al.), while keeping React library and project build concerns separate from your non-React client application.

interReaction is an ideal solution, for modernizing an aging client application, or replacing it, feature-by-feature, in a more sane, prepared, and maintainable way.

**NOTE: There are both React and Preact builds! This README applies to both interReaction (the React build) and interPreaction (the Preact build), and both use the same interReaction namespace, for method calls.

Contents

About
Quickstart
Methods
Advanced Topics

• Building From Source
• Running Tests
• Smoke Testing
• Cleanup
• Project Structure

Author And License Info
Support This Project

About

interReaction provides a simple interface, with simple methods, for mounting, passing props to, and otherwise manipulating React components from within a non-React application.

Build your React application as a standard, standalone application. Continue maintaining your current non-React application, without mixing libraries or build concerns.

Your React component tree may be structured according to your own design, just as when building a standard, standalone React app, because it is a standard, standalone React app.

Use Webpack, Babel and file loaders.

Use Redux, middleware, theming, and internationalization providers, with implementation and inheritance, all standard.

interReaction is wholly non-opinionated, about your React application structure, build configuration, loaders, or other third-party libraries.

interReaction is wholly non-opinionated, about your non-React application structure, build configuration, loaders, or other third-party libraries.

interReaction has no knowledge of any application details, React or otherwise, aside from those components assigned to its internal management (and, that knowledge is intentionally very limited).

interReaction is available for both React and Preact applications.

Quickstart

Requirements

The only requirements for interReaction (React) are dependencies: "react": "^17.0.2", "react-dom": "^17.0.2", and "scheduler": "^0.20.2" (for react-dom).

The only requirement for interPreaction (Preact) is a dependency of: "preact": "^10.5.13".

In either case, these are peer dependencies, which will need, alongside interReaction or interPreaction, to be installed and / or added to your project's package.json dependencies:

If using the React build (interReaction):
Install interReaction (React) and / or add as a dependency:

"dependencies": {

  "react": "^17.0.2",
  "react-dom": "^17.0.2",
  "scheduler": "^0.20.2",
  "interreaction": "^1.0.7",

}

Or:

$ npm install --save react@17.0.2 react-dom@17.0.2 scheduler@0.20.2 interreaction@1.0.7

If using the Preact build (interPreaction):
Install interPreaction (React) and / or add as a dependency:

"dependencies": {

  "preact": "^10.5.13",
  "interpreaction": "^1.0.7",

}

Or:

$ npm install --save preact@10.5.13 interpreaction@1.0.7

In your React application, initialize the interReaction instance, passing in component name to React component mappings, to be managed by interReaction (usually, in index.js, for example).

If using the React build (interReaction):

import InterReactionFactory from 'interreaction';

If using the Preact build (interPreaction):

import InterReactionFactory from 'interpreaction';

// REACT OR PREACT IMPORT, PROVIDER IMPORTS (REDUX, THEME, INTERNATIONALIZATION, ET AL.):
import React from 'react';
import { Provider } from 'react-redux';

// COMPONENTS TO BE MANAGED BY INTERREACTION:
import ComponentOne from 'component/ComponentOne';
import ComponentToo from 'component/ComponentToo';
import ComponentThree from 'component/ComponentThree';
import ComponentFour from 'component/ComponentFour';
import ComponentFive from 'component/ComponentFive';

// USUAL GLOBAL CSS IMPORTS, ETC:
import 'asset/style/App.scss';

// USUAL APP ROOT COMPONENT,
// WILL BE PASSED TO INTERREACTION:
class AppRootComponent extends React.Component {
  render() {
    return (
      // USUAL PROVIDERS, FOR INHERITANCE:
      <Provider store ={ AppStore }>
        // PASS this.props.children
        // INTERREACTION WILL ASSIGN (AND PROVIDERS WILL BE INHERITED):
        this.props.children
      </Provider>
    );
  }
}

// A MAPPING OF REACT COMPONENT NAMES, TO THEIR RESPECTIVE IMPORTS,
// WILL BE PASSED TO INTERREACTION:
const componentNameToComponentMappings = {
    ComponentOne,
    ComponentToo,
    ComponentThree,
    ComponentFour,
    ComponentFive
  };

// OPTIONAL CONFIG OBJECT:
const interReactionConfig = {
    // IF YOU WANT TO ASSIGN A CUSTOM CLASSNAME TO EACH CUSTOM ELEMENT:
    className: 'some_className',

    // IF YOU WANT TO ASSIGN A CUSTOM TAGNAME TO EACH CUSTOM ELEMENT:
    // (MUST CONFORM TO TAGNAME RULES FOR WEB COMPONENTS CUSTOM ELEMENTS)
    // (IF NOT SET, TAGNAME WILL DEFAULT TO: "inter-reaction")
    tagName: 'some-tagname',

    // IF YOU WANT TO ASSIGN THE DEFAULT,
    // INTERNAL CLASSNAME TO EACH CUSTOM ELEMENT:
    // (WILL ADD CLASSNAME: "interReaction" TO EACH CUSTOM ELEMENT)
    shouldApplyDefaultClassName: true,

    // IF YOU WANT CONSOLE LOG OUTPUT, FOR DEBUGGING:
    shouldEnableDebugging: (process.env.NODE_ENV === 'development')
  };

// THIS IS WHERE THE MAGIC HAPPENS!
InterReactionFactory.init(
  // REQUIRED:
  AppRootComponent,

  // REQUIRED:
  componentNameToComponentMappings,

  // OPTIONAL:
  interReactionConfig
);

In your non-React client application, add tags for, or otherwise import your React application .js and .css bundles.

interReaction will, on initialization, scan the DOM, for any statically-defined / pre-defined interReaction Custom Elements, by tagName, and assign a React component instance, by compName.

Your defined Custom Element may also have a compid and / or comp-group attribute, if the component should be associated to a group (comp-group === compGroup), or have an action performed upon it, uniquely (comp-id === compId).

<link href="location/of/your/react-css-bundle.css" rel="stylesheet" />
<script src="location/of/your/react-js-bundle.js" type="text/javascript"></script>

<!-- ON INITIALIZATION, INTERREACTION WILL MOUNT A NEW REACT COMPONENT INSTANCE, BY compName, INSIDE THIS CUSTOM ELEMENT -->
<inter-reaction comp-name="ComponentToo" comp-id="someUniqueId" comp-group="someGroupName"></inter-reaction>

In your non-React client application, add logic, for including React components, using interReaction.

const doInterReactionStuffs = function() {

  // CREATE A NEW INTERREACTION CUSTOM ELEMENT AND APPEND IT TO THE DOM:
  document.body.appendChild(
    interReaction.createElement({
      compName: 'ComponentOne',
      compId: 'compOneId'
    })
  );

  // ASSIGN A NEW REACT COMPONENT INSTANCE, BY compName, TO THE INTERREACTION CUSTOM ELEMENT,
  // BY compId,
  // AND PASS SOME INITIAL PROPS:
  interReaction.assign({
    compName: 'ComponentOne',
    compId: 'compOneId',
    compProps: {
      somePropkey: 'some prop value'
    }
  });

  // ASSIGN A NEW REACT COMPONENT,
  // BY compName,
  // TO EACH DOM ELEMENT FOUND BY PROVIDED QUERY SELECTOR:
  interReaction.createAssignToDomSelector(
    { compName: 'ComponentToo' },
    'document > body .someClassNameSelector'
  );

  // ASSIGN A NEW REACT COMPONENT,
  // BY compName,
  // TO THE PROVIDED DOM ELEMENT:
  interReaction.createAssignToDomElement(
    { compName: 'ComponentThree' },
    document.body.querySelector(.someOtherClassNameSelector)
  );
};


if (typeof interReactionReadyState !== 'undefined') {

  // CHECK THE WINDOW / GLOBAL 'interReactionReadyState' property:
  if (interReactionReadyState === 'ready') {
    doInterReactionStuffs();
  }

} else {

  // WAIT FOR THE 'interReactionInstanceReady' EVENT:
  document.addEventListener('interReactionInstanceReady', doInterReactionStuffs);

}

Methods

Common Contract:

All methods assigned to the golabl interReaction instance (also referred to as "actions") take a details arg, of type Object<String,String> or Object<String,Array<Object>>.

This further eases implementation, by creating an environment of general, repeatable familiarity.
From the details arg, for each method, the following fields are accepted:

compName

Type: String: in most cases, the compName field is required, in the absence of either compGroup or compList.
This field identifies the component, upon which to perform the desired action. It must match a component name existing in the component name to component mappings passed to the interReaction instance, via the InterReactionFactory.init method.

Example:

{ compName: 'SomeCompName' }

compId

Type: String: the compId field, when assigned to a component being added to the DOM, should be unique. When this field is present, an action will be performed upon only that singular component instance, to which the compId is assigned. Otherwise, the action will be performed upon all component instances which share the component name compName field value.

Example:

{ compName: 'SomeCompName', compId: 'someCompId' }

compGroup

Type: String: a compGroup field may be assigned, to several or many components, upon which an action should be performed. Components associated to a group do not need to have any relation to each other. They are simply multiple components, upon which you want an action executed, with a single method call. Except when being assigned, when compGroup is a populated field, generally, compName is not needed, because interReaction tracks, internally, which component instances are associated to which groups.

Example:

{ compGroup: 'groupName' }

compProps

Type: Object<String,?>: the compProps field is used with methods which pass props to React components, such as interReaction.update.

Example:

{ compName: 'SomeComp',
  compProps: { somePropKey: 'some prop value' }
}

compList

Type: Array<Object>: the compList field is used, when an action should be executed on multiple component insances, by compName (with or without compId), or compGroup.

Example:

{ compList: [
  { compName: 'SomeCompName' },
  { compGroup: 'groupName' },
  { compName: 'SomeOtherCompName', compId: 'someOtherCompId' },

  { compName: 'AnotherCompName',
    compId: 'anotherCompId',
    compProps: { somePropKey: 'some prop value' }
  }
] }

compReplacement

Type: String: the compReplacement field is a component name, used by method interReaction.replace, to replace a React component instance with an instance which has a matching component name.

Examples:

{ compName: 'SomeCompName', compReplacement: 'SomeOtherCompName' }

{ compGroup: 'groupName', compReplacement: 'SomeCompName' }

Methods:

.createElement(Object<String,String>{ details })

Returns a new interReaction Custom Element instance, to be appended to the DOM.

Args (1):

• details (Object<String,String>): Key : value pairs, which describe the React component to be mounted inside the Custom Element.
  • Fields:
    • compName (String, required): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance, of a component. should be actionable.
    • compGroup (String, optional): if the component instance should be associated to a group.
    • className (String, optional): a className to add to the Custom Element instance (this will be in addition to any classNames assigned to the interReaction instance config).
  • See: Common Contract, above, for more information, about details object fields. Returns:
    A new interReaction Custom Element instance, to be appended to the DOM.

Example:

// APPENDING A NEW interReaction Custom Element TO DOM document:
document.appendChild(
  interReaction.createElement({
    // REQUIRED:
    compName: 'SomeCompName',

    // OPTIONAL:
    compId: 'someCompID',

    // OPTIONAL:
    compGroup: 'someCompGroupName',
  })
);

.assign(Object<String,String|Array<Object>>{ details })

Assigns a new React component instance, to an interReaction Custom Element, by compName details field, and compId details field, if compId details field is present.

If compList details field is provided, in place of compName, assigns each React component instance, to its respective Custom Element instance, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be mounted inside the Custom Element(s).
  • Fields:
    • compName (String, required, if no compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance, of a component. should be actionable.
    • compGroup (String, optional): associates the component to a group.
    • compList (Array<Object>, required, if no compName): if more than one React component should be assigned.
    • compProps (Object<String,?>, optional): contains key : value pairs, to be passed as props, to the React component instance.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName, compId, compGroup, AND compProps:
interReaction.assign({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID',

  // OPTIONAL:
  compGroup: 'someCompGroupName',

  // OPTIONAL:
  compProps: {
      somePropsKey: 'some props value'
    }
});

// WITH compList:
interReaction.assign({
  compList: [
    { compName: 'SomeCompName' },
    { compName: 'SomeOtherCompName', compId: 'someCompId' },
    { compName: 'AnotherCompName', compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'YetAnotherCompName',
    
      // OPTIONAL:
      compId: 'someOtherCompID',
    
      // OPTIONAL:
      compGroup: 'someOtherCompGroupName'
    }
  ]
});

.createAssignToDomElement(Object<String,String|Array<Object>>{ details }, Element domElement, String position)

Creates a new interReaction Custom Element, adds it to the provided DOM Element, with positioning relative to siblings, according to the provided position, and assigns a new React component instance, by compName details field (and compId, if compId details field is present).

If compList details field is provided, in place of compName, creates each interReaction Custom Element, adds each to the provided DOM Element, with positioning relative to siblings, according to the provided position, and assigns each React component instance, to its respective Custom Element instance, per each array member object compName details field (and compId, if compId details field is present).

Args (3):

• details (Object<String,String|Array<Object>>, required): Key : value pairs, which describe the React component(s) to be mounted inside the Custom Element(s).

  • Fields:
    • compName (String, required, if no compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be actionable.
    • compList ((Array<Object<String,String>>, required, if no compName): if more than one intrerReaction Custom Element, by more than one compName, should be created and added to the DOM, and React component instances be assigned.
    • compGroup (String, optional): associates the component instance(s) to a group.
    • compProps (Object<String,?>, optional): contains key : value pairs, to be passed as props, to the React component instance(s).
  • See: Common Contract, above, for more information, about details object fields.

• domElement (DOM Element, required): DOM Element, to which the new Custom Element, with assigned React component, should be added.

• positioning (String, optional, defaults to: 'append'): one of: 'append' (add after DOM Element children), 'prepend' (add before DOM Element children), or 'replace' (replace DOM Element children).

Returns:
undefined

Examples:

// WITH compName, compId, AND compProps:
interReaction.createAssignToDomElement(
  {
    // REQUIRED:
    compName: 'SomeCompName',
  
    // OPTIONAL:
    compId: 'someCompID',
  
    // OPTIONAL:
    compProps: {
        somePropsKey: 'some props value'
      }
  },
  document.body,
  'append'
);

// WITH compGroup:
interReaction.createAssignToDomElement(
  { compGroup: 'someCompGroupName' },
  document.body,
  'append'
);

// WITH compList:
interReaction.createAssignToDomElement(
  { compList: [
    { compName: 'SomeCompName' },
    { compName: 'SomeOtherCompName', compId: 'someCompId' },
    { compName: 'AnotherCompName', compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'YetAnotherCompName',
    
      // OPTIONAL:
      compId: 'someOtherCompID',
    
      // OPTIONAL:
      compProps: {
          somePropsKey: 'some props value'
        }
    }
  ]},
  document.body,
  'append'
);

.createAssignToDomSelector(Object<String,String|Array<Object>>{ details }, String selector, String position)

Creates new interReaction Custom Elements, adds them to the DOM Elements found, by the provided query selector, with positioning relative to siblings, according to the provided position, and assigns new React component instances, by compName details field (and compId, if compId details field is present).

If compList details field is provided, in place of compName, creates each interReaction Custom Element, adds each to the DOM Elements found, by the provided query selector, with positioning relative to siblings, according to the provided position, and assigns each React component instance, to its respective Custom Element instance, per each array member object compName details field (and compId, if compId details field is present).

Args (3):

• details (Object<String,String|Array<Object>>, required): Key : value pairs, which describe the React component(s) to be mounted inside the Custom Element(s).

  • Fields:
    • compName (String, required, if no compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be actionable.
    • compList ((Array<Object<String,String>>, required, if no compName): if more than one intrerReaction Custom Element, by more than one compName, should be created and added to the DOM, and React component instances be assigned.
    • compGroup (String, optional): associates the component instance(s) to a group.
    • compProps (Object<String,?>, optional): contains key : value pairs, to be passed as props, to the React component instance(s).
  • See: Common Contract, above, for more information, about details object fields.

• querySelector (String, required): query selector, used to find DOM Eleemnts, to which new Custom Elements, with assigned React components, should be added.

• positioning (String, optional, defaults to: 'append'): one of: 'append' (add after DOM Element children), 'prepend' (add before DOM Element children), or 'replace' (replace DOM Element children).

Returns:
undefined

Examples:

// WITH compName, compId, AND compProps:
interReaction.createAssignToDomSelector(
  {
    // REQUIRED:
    compName: 'SomeCompName',
  
    // OPTIONAL:
    compId: 'someCompID',
  
    // OPTIONAL:
    compProps: {
        somePropsKey: 'some props value'
      }
  },
  'document > body .someElementClassName',
  'append'
);

// WITH compGroup:
interReaction.createAssignToDomSelector(
  { compGroup: 'someCompGroupName' },
  'document > body .someElementClassName',
  'append'
);

// WITH compList:
interReaction.createAssignToDomSelector(
  { compList: [
    { compName: 'SomeCompName' },
    { compName: 'SomeOtherCompName', compId: 'someCompId' },
    { compName: 'AnotherCompName', compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'YetAnotherCompName',
    
      // OPTIONAL:
      compId: 'someOtherCompID',
    
      // OPTIONAL:
      compProps: {
          somePropsKey: 'some props value'
        }
    }
  ]},
  'document > body .someElementClassName',
  'append'
);

.mount(Object<String,String|Array<Object>>{ details })

Mounts a React component instance, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, mounts all React component instances associated to the compGroup.

If compList details field is provided, in place of compName, mounts each React component instance, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be mounted.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be mounted.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be mounted.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be mounted.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.mount({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID'
});

// WITH compGroup:
interReaction.mount({ compGroup: 'someCompGroupName' });

// WITH compList:
interReaction.mount({
  compList: [
    { compName: 'SomeCompName' },
    { compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID'
    }
  ]
});

.unmount(Object<String,String|Array<Object>>{ details })

Unmounts a React component instance, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, unmounts all React component instances associated to the compGroup.

If compList details field is provided, in place of compName, unmounts each React component instance, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be unmounted.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be unmounted.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be unmounted.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be unmounted.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.unmount({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID'
});

// WITH compGroup:
interReaction.unmount({ compGroup: 'someCompGroupName' });

// WITH compList:
interReaction.unmount({
  compList: [
    { compName: 'SomeCompName' },
    { compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID'
    }
  ]
});

.remount(Object<String,String|Array<Object>>{ details })

Remounts (unmounts, then mounts) a React component instance, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, remounts (unmounts, then mounts) all React component instances associated to the compGroup.

If compList details field is provided, in place of compName, remounts (unmounts, then mounts) each React component instance, per each array member object compName details field (and compId, if compId details field is present).

(In the case that a component instance is already unmounted, .remount will mount the component instance.)

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be remounted.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be remounted.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be remounted.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be remounted.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.remount({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID'
});

// WITH compGroup:
interReaction.remount({ compGroup: 'someCompGroupName' });

// WITH compList:
interReaction.remount({
  compList: [
    { compName: 'SomeCompName' },
    { compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID'
    }
  ]
});

.toggleMount(Object<String,String|Array<Object>>{ details })

Mounts or unmounts (whichever is opposite to the current mount status) a React component instance, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, mounts or unmounts (whichever is opposite to the current mount status) all React component instances associated to the compGroup.

If compList details field is provided, in place of compName, mounts or unmounts (whichever is opposite to the current mount status) each React component instance, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be toggle mounted.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be toggle mounted.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be togle mounted.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be toggle mounted.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.toggleMount({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID'
});

// WITH compGroup:
interReaction.toggleMount({ compGroup: 'someCompGroupName' });

// WITH compList:
interReaction.toggleMount({
  compList: [
    { compName: 'SomeCompName' },
    { compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID'
    }
  ]
});

.remove(Object<String,String|Array<Object>>{ details })

Unmounts, then removes, from interReaction component management, a React component instance, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, unmounts then removes, from interReaction component management, all React component instances associated to the compGroup.

If compList details field is provided, in place of compName, unmounts, then removes, from interReaction component management, each React component instance, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be unmounted, then removed, from interReaction component management.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be unmounted and removed, from interReaction component management.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be unmounted and removed, from interReaction component management.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be unmounted and removed, from interReaction component management.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.remove({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID'
});

// WITH compGroup:
interReaction.remove({ compGroup: 'someCompGroupName' });

// WITH compList:
interReaction.remove({
  compList: [
    { compName: 'SomeCompName' },
    { compGroup: 'someCompGroupName' },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID'
    }
  ]
});

.replace(Object<String,String|Array<Object>>{ details })

Replaces a React component instance, with one named by details field compReplacement, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, replaces all React component instances, associated to the compGroup with those named by details field compReplacement.

If compList details field is provided, in place of compName, replaces each React component instance, with those named by details fields compReplacement, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s) to be mounted inside the Custom Element(s).
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should be replaced.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should be replaced.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should be replaced.
    • compReplacement (String, required (returns without error, if absent)): the name assigned to the component, which should replace the component named by compName.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.replace({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID',

  // REQUIRED (returns without error, if absent):
  compReplacement: 'SomeOtherCompName'
});

// WITH compGroup:
interReaction.replace({
  // REQUIRED:
  compGroup: 'someCompGroupName',

  // REQUIRED (returns without error, if absent):
  compReplacement: 'SomeOtherCompName'
});

// WITH compList:
interReaction.replace({
  compList: [
    {
      compName: 'SomeCompName',
      compReplacement: 'SomeOtherCompName'
    },
    {
      compGroup: 'someCompGroupName',
      compReplacement: 'SomeOtherCompName'
    },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID',

      // REQUIRED (returns without error, if absent):
      compReplacement: 'SomeOtherCompName'
    }
  ]
});

.update(Object<String,String|Array<Object>>{ details })

Passes props to a React component instance, properties provided by details field compProps, by compName details field, and compId details field, if compId details field is present.

If compGroup details field is provided, in place of compName, passes props to all React component instances, associated to the compGroup, properties provided by details field compProps.

If compList details field is provided, in place of compName, passes props to each React component instance, properties provided by details field compProps, per each array member object compName details field (and compId, if compId details field is present).

Args (1):

• details (Object<String,String|Array<Object>>): Key : value pairs, which describe the React component(s), to which props should be passed.
  • Fields:
    • compName (String, required, if no compGroup or compList): the name assigned to the component, in the mappings assigned to the interReaction instance.
    • compId (String, optional): a unique ID, assigned to the the component instance, when only one instance of a component should receive props.
    • compGroup (String, required, if no compName or compList): when component instances associated to the same group should receive propps.
    • compList (Array<Object>, required, if no compName or compGroup): if more than one React component instance, by more than one compName and / or compGroup, should receive props.
    • compProps (Object<String,?>, required (returns without error, if absent)): contains key : value pairs, to be passed as props, to the React component instance.
  • See: Common Contract, above, for more information, about details object fields.

Returns:
undefined

Examples:

// WITH compName AND compId:
interReaction.update({
  // REQUIRED:
  compName: 'SomeCompName',

  // OPTIONAL:
  compId: 'someCompID',

  // REQUIRED (returns without error, if absent):
  compProps: {
      somePropsKey: 'some props value'
    }
});

// WITH compGroup:
interReaction.update({
  // REQUIRED:
  compGroup: 'someCompGroupName',

  // REQUIRED (returns without error, if absent):
  compProps: {
      somePropsKey: 'some props value'
    }
});

// WITH compList:
interReaction.update({
  compList: [
    {
      compName: 'SomeCompName',
      compProps: {
          somePropsKey: 'some props value'
        }
    },
    {
      compGroup: 'someCompGroupName',
      compProps: {
          somePropsKey: 'some props value'
        }
    },
    {
      // REQUIRED:
      compName: 'SomeOtherComp',
    
      // OPTIONAL:
      compId: 'someOtherCompID',

      // REQUIRED (returns without error, if absent):
      compProps: {
          somePropsKey: 'some props value'
        }
    }
  ]
});

Advanced Topics

Building From Source

There are separate builds, for interReaction (React) and interPreaction (Preact).

To begin, clone the github repository:

$ git clone https://github.com/antonio-malcolm/interreaction.git

As of the latest update to this README, this project uses the following versions, of NodeJS, npm, and pnpm:

NodeJS: v14.17.1
npm: v6.14.13
pnpm: v6.9.1

To ensure you are using the current, correct versions, refer to the engines block, in package.json The author of this project uses nvm, to install and switch between NodeJS and npm versions, and doing so is highly recommended.

This project uses pnpm, to manage dependencies and workspaces, and it is also used to execute tasks, within the task management modules.
To install pnpm (current project version):

$ npm install -g pnpm@6.9.1

After installing pnpm, install the project dependencies:

$ pnpm install

There are separate builds, for interReaction (React) and interPreaction (Preact).
After successful installation of the project dependencies, you may build any one or all of the development, production, or release builds. Each build is isolated, under directory: workspaces/interreaction/build/dist/[dev, prod, release].

interReaction (React) dev build:

$ pnpm run build:interreaction:dev

interReaction (React) prod build:

$ pnpm run build:interreaction:prod

interReaction (React) release build:

$ pnpm run build:interreaction:release

interPreaction (Preact) dev build:

$ pnpm run build:interpreaction:dev

interPreaction (Preact) prod build:

$ pnpm run build:interpreaction:prod

interPreaction (Preact) release build:

$ pnpm run build:interpreaction:release

Running Tests

To run all tests (unit + integration tests):

$ pnpm run test:interreaction

Aside from test console output, test reports are generated, for both results and coverage, which are accessible from your web browser.
After tests have been run, start the projects built-in server, and navigate to the following local URLs, in your web browser: To clean the interreaction build directory:

$ pnpm run start

http://localhost:3001/test/report/interreaction/mochawesome/Test_Report_interreaction.html
http://localhost:3001/test/report/interreaction/nyc/index.html

Smoke Testing

There are separate smoke tests, for interReaction (React) and interPreaction (Preact).
Smoke testing can be done, one at a time, for either the React or Preact builds.

This project comes with React components, Redux state, and REST utilities which are used to test interReaction in a real-world scenario.
To begin the test, build the release package (used as a smoke test dependency), and start the project's built-in server.

interReaction (React) smoke test:

$ pnpm run build:interreaction:release
$ pnpm run start:interreaction

interPreaction (Preact) smoke test:

$ pnpm run build:interpreaction:release
$ pnpm run start:interpreaction

After successful build and server start, navigate to the following local URL, using your web browser:
http://localhost:3001/mmry/interreaction-test.html

If the build and server start were successful, you should see the following test page:

Cleanup

There are several options, for performing project cleanup.

To clean all workspace dependency, build, and test output directories:

$ pnpm run clean

To clean the interReaction (React) dependency, build, and test output directories:

$ pnpm run clean:interreaction

To clean the interReaction (React) dependency directory:

$ pnpm run clean:interreaction:dependency

To clean the interReaction (React) build directory:

$ pnpm run clean:interreaction:build

To clean the interPreaction (Preact) dependency, build, and test output directories:

$ pnpm run clean:interpreaction

To clean the interPreaction (Preact) dependency directory:

$ pnpm run clean:interpreaction:dependency

To clean the interPreaction (Preact) build directory:

$ pnpm run clean:interpreaction:build

To clean the test output directory:

$ pnpm run clean:test

Project Structure

There are workspace entries for both interReaction (React) and interPreaction (Preact).
Below is a general overview of the project structure, i.e., "where to find the relevant things".

interReaction (React) source code:
workspaces/interreaction/src/interreaction/

interReaction (React) build output (after build, you will find child directories dist/[dev, prod, release]):
workspaces/interreaction/build/

interPreaction (Preact) source code:
workspaces/interpreaction/src/interreaction/

interPreaction (Preact) build output (after build, you will find child directories dist/[dev, prod, release]):
workspaces/interpreaction/build/

interReaction test modules: test/spec/interreaction/

Test output (genrated after running tests) test/output/

Author And License Info

interReaction is authored by, and copyright 2021 to present, Antonio Malcolm.
All rights reserved.

interReaction (A.K.A., "interReaction", "InterReaction", "interpreaction", "interPreaction", or "InterPreaction") is licensed under the BSD 3-Clause license, and is subject to the terms of the BSD 3-Clause license, found in the LICENSE file, in the root directory of this project. If a copy of the BSD 3-Clause license cannot be found, as part of this project, you can obtain one, at: https://opensource.org/licenses/BSD-3-Clause

Support This Project

This software is built with the greatest care and attention to detail, and thoroughly tested.
Any support is greatly appreciated!