@flowerforce/flower-react 3.7.2 → 4.0.1-beta.0

package/README.md

@@ -2,7 +2,8 @@
 
 <a alt="Flower logo" href="https://flowerjs.it/" target="_blank" rel="noreferrer"><img src="https://flowerjs.it/_next/static/media/flower-logo.bb32f863.svg" width="50"></a>
 
-Flower React is a front-end development library built on top of Flower Core, specifically designed for React applications. It seamlessly integrates Flower's powerful capabilities into React projects, providing a user-friendly interface to create, modify, and monitor workflows.
+Flower React is a front-end development library built on top of Flower Core, specifically designed for React applications.
+It seamlessly integrates Flower's powerful capabilities into React projects, providing a user-friendly interface to create, modify, and monitor workflows.
 
 For more info [flowerjs.it/](https://flowerjs.it/)
 
@@ -15,8 +16,6 @@ For more info [flowerjs.it/](https://flowerjs.it/)
 - **State Management**: Built-in state management to keep track of workflow changes and updates.
 - **Event System**: Customizable event handling to respond to user interactions and changes within the workflow.
 - **Serialization**: Convert workflows to JSON for easy storage and retrieval. (only server side flow)
-- **Validation**: Ensure workflows follow predefined rules and constraints to maintain integrity.
-- **Form Validation**: Built-in functionalities to validate form inputs within nodes, ensuring data integrity and correctness.
 - **History Management**: Internal management of flow history, tracking node traversal and changes for debugging and visualization purposes.
 
 ### Installation
@@ -45,7 +44,11 @@ yarn add @flowerforce/flower-react
 
 ## Configuration
 
-The **FlowerProvider** component wraps the entire application, providing a global context to manage the application flow.
+
+Flower React works with redux global state.
+
+If you starts an application with Flower React from scratch, you need to wrap your application with **FlowerProvider**
+The **FlowerProvider** component wraps the entire application, providing a global redux context to manage the application flow.
 
 ```jsx
 import React from 'react'
@@ -59,7 +62,69 @@ function Root() {
   )
 }
 ```
-> You can pass the prop `enableReduxDevtool` to the `FlowerProvider` to show the Flower Store data inside the redux devtool of your browser.
+
+If your application is already built with redux as global state manager, you can use differents approaches:
+
+- Separates Providers
+
+In this case, you need to wrap your application with the **FlowerProvider** component in addition to the classic Redux provider.
+The order of providers is not relevant, since their redux contexts are different.
+n.b.: FlowerProvider generates a store instance with `FlowerData slice` from `flower-react-form`
+
+```jsx
+import React from 'react'
+import { Provider } from 'react-redux'
+import { yourStore } from 'yourStore'
+import { FlowerProvider } from '@flowerforce/flower-react'
+
+function Root() {
+  return (
+    <Provider store={yourStore}>
+      <FlowerProvider>  
+        <App />
+      </FlowerProvider>
+    </Provider>
+  )
+}
+```
+
+- Single Provider
+
+For this scenario, we provides ***createStoreWithFlower***
+This functions takes a `configureStoreOptions` object (same as createStore from redux) and an optional `middlewaresBlacklist`, since flower inject automatically some middlewares in its store.
+To generate slices fully compatible, you can use ***createSliceWithFlower***, a function same as `createSlice` from redux.
+Let's see the needed configuration
+```jsx
+import React from 'react'
+import { Provider } from 'react-redux'
+import { FormProvider, createStoreWithFlower, createSliceWithFlower } from '@flowerforce/flower-react'
+
+const myStoreWithFlower = createSliceWithFlower({
+  name: 'myStore',
+  initialData: {},
+  reducers: {
+    add: (state) => {
+      state.count += 1
+    }
+  }
+})
+
+const storeWithFlower = createStoreWithFlower({
+  reducer: {
+      myStore: myStoreWithFlower.reducer,
+    }
+})
+
+function Root() {
+  return (
+    <Provider store={storeWithFlower}>
+      <App />
+    </Provider>
+  )
+}
+```
+
+In this scenario, we need a single provider, so we use the default redux provider
 
 ## How to use
 
@@ -110,10 +175,9 @@ Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-9
 
 This prop allows you to configure the following fields:
 
- 1) `startId`: string
- 2) `current`: string
- 3) `history`: string[]
-
+ 1) `startId`: string - First node of current flow
+ 2) `current`: string - Current node of current flow
+ 3) `history`: string[] - History of nodes in current flow
 
 
 ### Navigate with routes
@@ -210,64 +274,6 @@ export const Page = () => {
 
 Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-forked-5c4rs4)
 
-### Basic WRITE | READ State
-
-To modify the internal state of Flower, besides passing initialData as a prop, we can always modify and read the state through the components **FlowerField** and **FlowerValue**.
-
-_FlowerField_ pass two props, onChange and value, to properly modify and read the value from the state of Flower.
-_FlowerValue_ pass value, to properly read the value from the state of Flower.
-
-Here's an example of how it works:
-
-```jsx
-import React from 'react'
-import {
-  Flower,
-  FlowerRoute,
-  FlowerNavigate,
-  FlowerNode,
-  FlowerField,
-  FlowerValue
-} from '@flowerforce/flower-react'
-
-export const Page = () => {
-  return (
-    <Flower name="demo">
-      <FlowerNode
-        id="step1"
-        to={{
-              step3: {
-                rules: { $and: [{ skipStep2: { $eq: true } }] }
-              },
-              step2: null
-            }}
-        >
-        ...
-
-        <FlowerField id="skipStep2">
-          {({ onChange, value }) => <input type="checkbox" checked={value} onChange={e => onChange(e.target.checked)} />}
-        </FlowerField>
-
-        <FlowerNavigate action="next">
-          <button>click me to go next</button>
-        </FlowerNavigate>
-      </FlowerNode>
-
-      <FlowerNode id="step2">...</FlowerNode>
-
-      <FlowerNode id="step3">
-        <FlowerValue id="enableFinal">
-          {({ value }) => <span>skipStep2: {String(!!value)}</span>}
-        </FlowerValue>
-      </FlowerNode>
-
-    </Flower>
-  )
-}
-
-```
-
-Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-3-forked-r3hgnj)
 
 ### Action Node
 
@@ -424,7 +430,7 @@ export const Page = () => {
 
 Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-forked-6wj3l9)
 
-#### External use
+#### External use of useFlower
 
 ```jsx
 import React from 'react'
@@ -499,11 +505,211 @@ export const Page = () => {
 }
 ```
 
-## Form
 
-Flower enables the quick creation of forms.
 
-It keeps track of the form's validity status. Not only does this status facilitate displaying error messages to the user, but it can also be leveraged to implement flow rules.
+
+## Operators Rules
+
+The "rules" in Flower are used to define conditions and conditional behaviors within the workflow. These rules allow to dynamically change the display or behavior of certain fields or components based on specific conditions.
+
+The rules schema follows the MongoDB style, below is the list of available operators:
+
+- $exists: Checks if a value exists or not.
+- $eq: Checks if two values are equal.
+- $ne: Checks if two values are not equal.
+- $gt: Checks if the first value is greater than the second.
+- $gte: Checks if the first value is greater than or equal to the second.
+- $lt: Checks if the first value is less than the second.
+- $lte: Checks if the first value is less than or equal to the second.
+- $strGt: Checks if the length of a string is greater than the specified value.
+- $strGte: Checks if the length of a string is greater than or equal to the specified value.
+- $strLt: Checks if the length of a string is less than the specified value.
+- $strLte: Checks if the length of a string is less than or equal to the specified value.
+- $in: Checks if a value is present in a given array.
+- $nin: Checks if a value is not present in a given array.
+- $all: Checks if all values are present in a given array.
+- $regex: Checks if a string matches a regular expression.
+
+### Examples
+
+Rules in $and | $or
+
+```jsx
+<FlowerNode id="node"
+  to={{
+    node2: {
+      rules: { $and: [
+        { myValue: { $exists: true } },
+        { myValue: { $strGt: 6 } }
+
+      ]}
+    }
+    }}>
+        ...
+</Flower>
+
+<FlowerNode id="node"
+  to={{
+    node2: {
+      rules: { $or: [
+        { myValue: { $exists: false } },
+        { myValue: { $strGt: 6 } }
+
+      ]}
+    }
+    }}>
+        ...
+</Flower>
+
+```
+
+Compare state value, use '$ref:'
+
+```jsx
+<Flower name="demo" initialData={{ myValue1: 'test', myValue2: 'test2' }}>
+<FlowerNode id="node"
+  to={{
+    node2: {
+      rules: [
+        { myValue1: { $eq: '$ref:myValue2' } }
+      ]}
+    }}>
+        ...
+</Flower>
+```
+
+## Display Rules
+
+Showing or Hiding Fields: You can use rules to show or hide specific fields based on user choices. For example, hiding a "Buttons" unless the user selects a certain option.
+
+We can use the FlowerRule component to hide a part of the UI according to certain rules.
+
+If the "alwaysDisplay" property is passed, however, the component will not be automatically hidden, but a "hidden" property will be provided when the rules are not met.
+
+### Example
+
+```jsx
+import React from 'react'
+import {
+  Flower,
+  FlowerRoute,
+  FlowerNode,
+  FlowerRule,
+  FlowerNavigate
+} from '@flowerforce/flower-react'
+
+export const Page = () => {
+  return (
+    <Flower name="demo" initialData={{ enableNav: true }}>
+      <FlowerNode id="step1" to={{ step2: null }}>
+        ...
+        {/* show / hidden based on rule */}
+        <FlowerRule rules={{ enableNav: { $eq: true } }}>
+          <p>Buttons nav are enabled</p>
+        </FlowerRule>
+        {/* always visible component, hidden prop is true when rule is not matched */}
+        <FlowerNavigate
+          action="next"
+          rules={{ enableNav: { $eq: true } }}
+          alwaysDisplay
+        >
+          {({ onClick, hidden }) => (
+            <button disabled={hidden} onClick={onClick}>
+              Next &#8594;
+            </button>
+          )}
+        </FlowerNavigate>
+        {/* visible only when rule is matched */}
+        <FlowerNavigate action="reset" rules={{ enableNav: { $eq: true } }}>
+          <button>Reset</button>
+        </FlowerNavigate>
+      </FlowerNode>
+      ...
+    </Flower>
+  )
+}
+```
+
+Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-forked-sfn6ml)
+
+
+# FlowerForm Integrations
+Next to FlowerReact, we find FlowerForm, another library designed to manage data and forms independently from the flow process.
+(add link to new form documentation)
+
+### Basic WRITE | READ State - move this in form
+
+To modify the internal state of Flower, besides passing initialData as a prop, we can always modify and read the state through the components **FlowerField** and **FlowerValue**.
+
+N.B.: We must use FlowerField component provided by `@flowerforce/flower-react-form`
+N.B.: We must use FlowerValue component provided by `@flowerforce/flower-react-shared`
+
+
+_FlowerField_ pass two props, onChange and value, to properly modify and read the value from the state of Flower.
+_FlowerValue_ pass value, to properly read the value from the state of Flower.
+
+Here's an example of how it works:
+
+```jsx
+import React from 'react'
+import {
+  Flower,
+  FlowerRoute,
+  FlowerNavigate,
+  FlowerNode
+} from '@flowerforce/flower-react'
+
+import {
+  FlowerField,
+} from '@flowerforce/flower-react-form'
+
+import { FlowerValue } from '@flowerforce/flower-react-shared'
+
+
+export const Page = () => {
+  return (
+    <Flower name="demo">
+      <FlowerNode
+        id="step1"
+        to={{
+              step3: {
+                rules: { $and: [{ skipStep2: { $eq: true } }] }
+              },
+              step2: null
+            }}
+        >
+        ...
+
+        <FlowerField id="skipStep2">
+          {({ onChange, value }) => <input type="checkbox" checked={value} onChange={e => onChange(e.target.checked)} />}
+        </FlowerField>
+
+        <FlowerNavigate action="next">
+          <button>click me to go next</button>
+        </FlowerNavigate>
+      </FlowerNode>
+
+      <FlowerNode id="step2">...</FlowerNode>
+
+      <FlowerNode id="step3">
+        <FlowerValue id="enableFinal">
+          {({ value }) => <span>skipStep2: {String(!!value)}</span>}
+        </FlowerValue>
+      </FlowerNode>
+
+    </Flower>
+  )
+}
+
+```
+
+Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-3-forked-r3hgnj)
+
+## Form - move this in form
+N.B.: `@flowerforce/flower-react-form` provides its own provider `FormProvider` and an equivalent of `<Flower>` component  called `<FlowerForm>`
+In this case we don't need to use it as form components reads from <Flower> context and mantains consistency between flowname and formname
+
+For more info [flowerjs.it/flower-react-form](https://flowerjs.it/flower-react-form) /// we must generate pages in website for specific documentation
 
 ### Basic Usage
 
@@ -512,11 +718,15 @@ import {
   Flower,
   FlowerNavigate,
   FlowerNode,
-  FlowerField,
   FlowerAction,
-  useFlower,
-  useFlowerForm
+  useFlower
 } from '@flowerforce/flower-react'
+
+import {
+  FlowerField,
+  useFlowerForm
+} from '@flowerforce/flower-react-form'
+
 import { useEffect } from 'react'
 import './styles.css'
 
@@ -610,7 +820,7 @@ export default function App() {
 
           <FlowerNavigate
             action="next"
-            rules={{ $and: [{ '$form.isValid': { $eq: true } }] }}
+            rules={{ $and: [{ '$data.isValid': { $eq: true } }] }}
             alwaysDisplay
           >
             {({ onClick, hidden }) => (
@@ -656,130 +866,6 @@ export default function App() {
 
 Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-forked-2f43gh)
 
-## Operators Rules
-
-The "rules" in Flower are used to define conditions and conditional behaviors within the workflow. These rules allow to dynamically change the display or behavior of certain fields or components based on specific conditions.
-
-The rules schema follows the MongoDB style, below is the list of available operators:
-
-- $exists: Checks if a value exists or not.
-- $eq: Checks if two values are equal.
-- $ne: Checks if two values are not equal.
-- $gt: Checks if the first value is greater than the second.
-- $gte: Checks if the first value is greater than or equal to the second.
-- $lt: Checks if the first value is less than the second.
-- $lte: Checks if the first value is less than or equal to the second.
-- $strGt: Checks if the length of a string is greater than the specified value.
-- $strGte: Checks if the length of a string is greater than or equal to the specified value.
-- $strLt: Checks if the length of a string is less than the specified value.
-- $strLte: Checks if the length of a string is less than or equal to the specified value.
-- $in: Checks if a value is present in a given array.
-- $nin: Checks if a value is not present in a given array.
-- $all: Checks if all values are present in a given array.
-- $regex: Checks if a string matches a regular expression.
-
-### Examples
-
-Rules in $and | $or
-
-```jsx
-<FlowerNode id="node"
-  to={{
-    node2: {
-      rules: { $and: [
-        { myValue: { $exists: true } },
-        { myValue: { $strGt: 6 } }
-
-      ]}
-    }
-    }}>
-        ...
-</Flower>
-
-<FlowerNode id="node"
-  to={{
-    node2: {
-      rules: { $or: [
-        { myValue: { $exists: false } },
-        { myValue: { $strGt: 6 } }
-
-      ]}
-    }
-    }}>
-        ...
-</Flower>
-
-```
-
-Compare state value, use '$ref:'
-
-```jsx
-<Flower name="demo" initialData={{ myValue1: 'test', myValue2: 'test2' }}>
-<FlowerNode id="node"
-  to={{
-    node2: {
-      rules: [
-        { myValue1: { $eq: '$ref:myValue2' } }
-      ]}
-    }}>
-        ...
-</Flower>
-```
-
-## Display Rules
-
-Showing or Hiding Fields: You can use rules to show or hide specific fields based on user choices. For example, hiding a "Buttons" unless the user selects a certain option.
-
-We can use the FlowerRule component to hide a part of the UI according to certain rules.
-
-If the "alwaysDisplay" property is passed, however, the component will not be automatically hidden, but a "hidden" property will be provided when the rules are not met.
-
-### Example
-
-```jsx
-import React from 'react'
-import {
-  Flower,
-  FlowerRoute,
-  FlowerNode,
-  FlowerRule,
-  FlowerNavigate
-} from '@flowerforce/flower-react'
-
-export const Page = () => {
-  return (
-    <Flower name="demo" initialData={{ enableNav: true }}>
-      <FlowerNode id="step1" to={{ step2: null }}>
-        ...
-        {/* show / hidden based on rule */}
-        <FlowerRule rules={{ enableNav: { $eq: true } }}>
-          <p>Buttons nav are enabled</p>
-        </FlowerRule>
-        {/* always visible component, hidden prop is true when rule is not matched */}
-        <FlowerNavigate
-          action="next"
-          rules={{ enableNav: { $eq: true } }}
-          alwaysDisplay
-        >
-          {({ onClick, hidden }) => (
-            <button disabled={hidden} onClick={onClick}>
-              Next &#8594;
-            </button>
-          )}
-        </FlowerNavigate>
-        {/* visible only when rule is matched */}
-        <FlowerNavigate action="reset" rules={{ enableNav: { $eq: true } }}>
-          <button>Reset</button>
-        </FlowerNavigate>
-      </FlowerNode>
-      ...
-    </Flower>
-  )
-}
-```
-
-Edit on [codesandbox/](https://codesandbox.io/p/sandbox/flower-react-example-1-forked-sfn6ml)
-
 
 # Debugging Your Flower Application with @flowerforce/devtool
 To enhance the debugging process of your Flower application, we offer a specialized library named @flowerforce/devtool. This tool is designed to provide a more convenient and powerful debugging experience.
@@ -927,3 +1013,8 @@ In any case, there is a JSON schema that will guide you in writing the file asso
 # Documentation
 
 The Flower React docs are published at [flowerjs.it/](https://flowerjs.it)
+
+
+
+
+