Merge pull request #11 from CarstenWickner/content-edit-functions

Author: CarstenWickner

CHANGELOG.MD

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+- Export of `updateStepData()` function for manipulating content of a single step node
+- Export of `updateGatewayData()` function for manipulating condition type associated with a single diverging gateway node
+- Export of `updateGatewayBranchData()` function for manipulating condition value associated with a single diverging gateway branch
+- Export of `validateFlow()` function (as alternative to `isFlowValid()`) throwing a descriptive error in case of an invalid flow
+
 ## [1.0.1] - 2020-02-23
 ### Added
 - Mentioning of all component props in README
@@ -28,5 +35,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enable customization of default condition type, number of branches and associated condition values for a newly added `DivergingGatewayNode`
 - Expose internal validation logic
 
+[Unreleased]: https://github.com/CarstenWickner/react-jsonschema-inspector/compare/v1.0.1...HEAD
 [1.0.1]: https://github.com/CarstenWickner/react-jsonschema-inspector/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/CarstenWickner/react-jsonschema-inspector/releases/tag/v1.0.0

README.md

@@ -8,6 +8,27 @@ Introducing a component for viewing/editing simple flow-charts but with the abil
 The layout is handled through CSS `grid` which avoids error-prone pixel calculations.
 The limited flexibility is accepted and even desired to concentrate on the more important content while still achieving a uniform design.
 
+Topics covered in this document are:
+- [Demo](#demo)
+- [Usage](#usage)
+    - [Installation from NPM](#installation-from-npm)
+    - [React Component Props of `<FlowModeler>`](#react-component-props-of-flowmodeler)
+        - [`flow` (required)](#flow-required)
+        - [`options`](#options)
+        - [`renderStep` (required)](#renderstep-required)
+        - [`renderGatewayConditionType`](#rendergatewayconditiontype)
+        - [`renderGatewayConditionValue`](#rendergatewayconditionvalue)
+        - [`onChange`](#onchange)
+        - [`editActions`](#editactions)
+    - [Additional Exports](#additional-exports)
+        - [`isFlowValid` function](#isflowvalid-function)
+        - [`validateFlow` function](#validateflow-function)
+        - [`updateStepData` function](#updatestepdata-function)
+        - [`updateGatewayData` function](#updategatewaydata-function)
+        - [`updateGatewayBranchData` function](#updategatewaybranchdata-function)
+    - [Example (read-only)](#example-read-only)
+    - [Example (structural editing, starting with empty "flow")](#example-structural-editing-starting-with-empty-flow)
+
 ## Demo
 
 Have a look at the [![Storybook][storybook-image]][storybook-url]
@@ -26,14 +47,14 @@ npm i react-flow-modeler
 Describing the whole data model being displayed, expecting an object with two fields:
 - `flow.firstElementId` – string containing the key to the `flow.elements` entry, that should follow the start node
 - `flow.elements` – object containing all "step" nodes and "diverging gateway" nodes as values
-  - "step" nodes are represented by an object that may contain the following fields:
-    - `data` – object in which any kind of additional information may be stored (in order to consider it in the `renderStep` function
-    - `nextElementId` – string containing the key to the `flow.elements` entry, that should follow this step (if omitted or without matching entry in `flow.elements`, it will point to the end node)
-  - "diverging gateway" nodes are represented by an object that may contain the following fields:
-    - `data` – object in which any kind of additional information may be stored (in order to consider it in the `renderGatewayConditionType` function
-    - `nextElements` (required, otherwise it is treated as "step" node) – array of branches from this gateway, each branch being represented by an object with the following fields:
-      - `conditionData` – object in which any kind of additional information may be stored (in order to consider it in the `renderGatewayConditionValue` function
-      - `id` – string containing the key to the `flow.elements` entry, that should follow this gateway branch (if omitted or without matching entry in `flow.elements`, it will point to the end node)
+    - "step" nodes are represented by an object that may contain the following fields:
+        - `data` – object in which any kind of additional information may be stored (in order to consider it in the `renderStep` function
+        - `nextElementId` – string containing the key to the `flow.elements` entry, that should follow this step (if omitted or without matching entry in `flow.elements`, it will point to the end node)
+    - "diverging gateway" nodes are represented by an object that may contain the following fields:
+        - `data` – object in which any kind of additional information may be stored (in order to consider it in the `renderGatewayConditionType` function
+        - `nextElements` (required, otherwise it is treated as "step" node) – array of branches from this gateway, each branch being represented by an object with the following fields:
+            - `conditionData` – object in which any kind of additional information may be stored (in order to consider it in the `renderGatewayConditionValue` function
+            - `id` – string containing the key to the `flow.elements` entry, that should follow this gateway branch (if omitted or without matching entry in `flow.elements`, it will point to the end node)
 
 #### `options`
 Currently only catering for one setting:
@@ -64,35 +85,82 @@ Render function for the condition label on a branch from a diverging gateway exp
 - `followingElement` – reference to the directly following element in the flow
 
 #### `onChange`
-Callback function that when present enables structural editing, receiving a single input object containing the following field:
-- `changedFlow` – updated `flow` that should be stored in some external state and provided again via the `flow` prop
+Callback function that when present enables structural editing,
+- receiving a single input object containing the following field:
+    - `changedFlow` – updated `flow` that should be stored in some external state and provided again via the `flow` prop to the `<Modeler>`
 
 #### `editActions`
 Object containing various customization options for the structural editing feature in the following fields:
 - `addDivergingBranch` – object for customizing the adding of branches to a diverging gateway, expecting any of the following fields:
-  - `className` – string overriding the default `"menu-item add-branch"` css classes on the corresponding context menu item
-  - `title` – string defining the tool-tip to show for the corresponding context menu item
-  - `isActionAllowed` – function for preventing adding branches to certain gateway, expecting a `boolean` to be returned based on the same single input object as on `renderGatewayConditionType` referring to the selected element
-  - `getBranchConditionData` – function for providing the default `conditionData` on a newly added diverging gateway branch based on the same single input object as on `renderGatewayConditionType`
+    - `className` – string overriding the default `"menu-item add-branch"` css classes on the corresponding context menu item
+    - `title` – string defining the tool-tip to show for the corresponding context menu item
+    - `isActionAllowed` – function for preventing adding branches to certain gateway, expecting a `boolean` to be returned based on the same single input object as on `renderGatewayConditionType` referring to the selected element
+    - `getBranchConditionData` – function for providing the default `conditionData` on a newly added diverging gateway branch based on the same single input object as on `renderGatewayConditionType`
 - `addFollowingStepElement` – object for customizing the adding of step nodes, expecting any of the following fields:
-  - `className` – string overriding the default `"menu-item add-step"` css classes on the corresponding context menu item
-  - `title` – string defining the tool-tip to show for the corresponding context menu item
-  - `isActionAllowed` – function for preventing adding step nodes after certain elements, expecting a `boolean` to be returned based on the reference to the selected element
-  - `getStepData` – function for providing the default `data` on a newly added step node based on the reference to the element where the corresponding context menu item was clicked
+    - `className` – string overriding the default `"menu-item add-step"` css classes on the corresponding context menu item
+    - `title` – string defining the tool-tip to show for the corresponding context menu item
+    - `isActionAllowed` – function for preventing adding step nodes after certain elements, expecting a `boolean` to be returned based on the reference to the selected element
+    - `getStepData` – function for providing the default `data` on a newly added step node based on the reference to the element where the corresponding context menu item was clicked
 - `addFollowingDivergingGateway` – object for customizing the adding of diverging gateway nodes, expecting any of the following fields:
-  - `className` – string overriding the default `"menu-item add-gateway"` css classes on the corresponding context menu item
-  - `title` – string defining the tool-tip to show for the corresponding context menu item
-  - `isActionAllowed` – function for preventing adding diverging gateways after certain elements, expecting a `boolean` to be returned based on the reference to the element where the corresponding context menu item was clicked
-  - `getGatewayData` – function for providing the default `data` on a newly added diverging gateway based on the reference to the selected element
-  - `getBranchConditionData`– function for providing an array of the default `conditionData` objects for each branch of a newly added diverging gateway based on the reference to the element where the corresponding context menu item was clicked; thereby also determining how many branches there are by default
+    - `className` – string overriding the default `"menu-item add-gateway"` css classes on the corresponding context menu item
+    - `title` – string defining the tool-tip to show for the corresponding context menu item
+    - `isActionAllowed` – function for preventing adding diverging gateways after certain elements, expecting a `boolean` to be returned based on the reference to the element where the corresponding context menu item was clicked
+    - `getGatewayData` – function for providing the default `data` on a newly added diverging gateway based on the reference to the selected element
+    - `getBranchConditionData`– function for providing an array of the default `conditionData` objects for each branch of a newly added diverging gateway based on the reference to the element where the corresponding context menu item was clicked; thereby also determining how many branches there are by default
 - `changeNextElement` – object for customizing the links between elements in the flow, expecting any of the following fields:
-  - `className` – string overriding the default `"menu-item change-next"` css classes on the corresponding context menu item
-  - `title` – string defining the tool-tip to show for the corresponding context menu item
-  - `isActionAllowed` – function for preventing links from certain elements to be changed, expecting a `boolean` to be returned based on the reference to the selected element
+    - `className` – string overriding the default `"menu-item change-next"` css classes on the corresponding context menu item
+    - `title` – string defining the tool-tip to show for the corresponding context menu item
+    - `isActionAllowed` – function for preventing links from certain elements to be changed, expecting a `boolean` to be returned based on the reference to the selected element
 - `removeElement` – object for customizing the removal of elements in the flow, expecting any of the following fields:
-  - `className` – string overriding the default `"menu-item remove"` css classes on the corresponding context menu item
-  - `title` – string defining the tool-tip to show for the corresponding context menu item
-  - `isActionAllowed` – function for preventing certain elements to be removed, expecting a `boolean` to be returned based on the reference to the selected element
+    - `className` – string overriding the default `"menu-item remove"` css classes on the corresponding context menu item
+    - `title` – string defining the tool-tip to show for the corresponding context menu item
+    - `isActionAllowed` – function for preventing certain elements to be removed, expecting a `boolean` to be returned based on the reference to the selected element
+
+### Additional Exports
+#### `isFlowValid` function
+- input: expecting a complete `flow` as single input parameter
+- output: returning a `boolean` response to indicate whether the given `flow` is deemed valid by the `<Modeler>`
+
+#### `validateFlow` function
+- input: expecting a complete `flow` as single input parameter
+- output: not returning anything in case of a valid `flow` but throwing an `Error` otherwise
+
+#### `updateStepData` function
+- inputs:
+    1. expecting a complete `flow` as first input parameter
+    2. expecting the `id` of a step node (i.e. identifying the step node under `flow.elements[id]`) as second input parameter
+    3. expecting a callback function as third input parameter
+        - input: the current `data` of the targeted step node will be provided as single input parameter
+        - output: the new `data` object to set on the targeted step node is expected to be returned
+- output: returning an object (that can be provided to your `onChange` function) containing the following field:
+    - `changedFlow` – updated `flow` that should be stored in some external state and provided again via the `flow` prop to the `<Modeler>`
+
+#### `updateGatewayData` function
+- inputs:
+    1. expecting a complete `flow` as first input parameter
+    2. expecting the `id` of a gateway node (i.e. identifying the gateway node under `flow.elements[id]`) as second input parameter
+    3. expecting a callback function as third input parameter
+        - input: the current `data` of the targeted gateway node will be provided as single input parameter
+        - output: the new `data` object to set on the targeted gateway node is expected to be returned
+    4. optionally catering for another callback function to be provided as fourth input parameter
+        - inputs:
+            1. the current `conditionData` of a branch of the targeted gateway node will be provided as first input parameter
+            2. the index of the respective branch of the targeted gateway node will be provided as second input parameter
+            3. an array of the current `conditionData` of all branches of the targeted gateway node will be provided as third input parameter
+        - ooutput: the new `conditionData` object to set on the respective branch of the targeted gateway node is expected to be returned
+- output: returning an object (that can be provided to your `onChange` function) containing the following field:
+    - `changedFlow` – updated `flow` that should be stored in some external state and provided again via the `flow` prop to the `<Modeler>`
+
+#### `updateGatewayBranchData` function
+- inputs:
+    1. expecting a complete `flow` as first input parameter
+    2. expecting the `id` of a gateway node (i.e. identifying the gateway node under `flow.elements[id]`) as second input parameter
+    3. expecting the index of the targeted branch of the gateway node (i.e. referring to `flow.elements[id].nextElements[index]`) as third input parameter
+    4. expecting a callback function as fourth input parameter
+        - input: the current `conditionData` of the targeted gateway branch will be provided as single input parameter
+        - output: the new `conditionData` object to set on the targeted gateway branch is expected to be returned
+- output: returning an object (that can be provided to your `onChange` function) containing the following field:
+    - `changedFlow` – updated `flow` that should be stored in some external state and provided again via the `flow` prop to the `<Modeler>`
 
 ### Example (read-only)
 ```javascript

package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-flow-modeler",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "description": "Modeler for customisable flow charts",
     "homepage": "https://CarstenWickner.github.io/react-flow-modeler/?path=/docs/flowmodeler--show-case",
     "author": "Carsten Wickner",

src/index.ts

@@ -1,3 +1,5 @@
 export { FlowModeler } from "./component/FlowModeler";
 
-export { isFlowValid } from "./model/pathValidationUtils";
+export { updateStepData, updateGatewayData, updateGatewayBranchData } from "./model/modelUtils";
+
+export { isFlowValid, validateFlow } from "./model/pathValidationUtils";