@flowerforce/flower-react 3.1.1 → 3.1.2-beta.1

package/dist/src/components/Flower.d.ts

@@ -1,9 +1,15 @@
 import React, { PropsWithChildren } from 'react';
+type FlowerInitalState = {
+    startId?: string;
+    current?: string;
+    history?: string[];
+};
 type FlowerClientProps = PropsWithChildren & {
     name: string;
     destroyOnUnmount?: boolean;
     startId?: string | null;
     initialData?: any;
+    initialState?: FlowerInitalState;
 };
-declare const component: React.MemoExoticComponent<({ children, name, destroyOnUnmount, startId, initialData }: FlowerClientProps) => React.JSX.Element | null>;
+declare const component: React.MemoExoticComponent<({ children, name, destroyOnUnmount, startId, initialData, initialState }: FlowerClientProps) => React.JSX.Element | null>;
 export default component;

package/dist/src/components/types/DefaultNode.d.ts

@@ -1,8 +1,25 @@
 export type FlowerNodeDefaultProps = {
+    /** Unique identifier for the node inside the Flow */
     id: string;
+    /** An object containing the informations about the node's links.
+     *
+     * Example: to={{ step2: { rules: { $and: [{ name: { $eq: 'John' } }] } } }}
+     *
+     * In that case, the FlowerNode is linked to the node with the ID 'step2'
+     *
+     * You can move from the current node to the step2 node only if the rules are satisfied
+     *
+     * Set it to null when you don't have rules
+     *
+     * Example: to={{ step2: null}
+     */
     to?: Record<string, any>;
+    /** The children of the FlowerNode */
     children?: React.ReactNode;
+    /** The function executed when you enter into this FlowerNode */
     onEnter?: () => void;
+    /** The function executed when you leave this FlowerNode */
     onExit?: () => void;
+    /** When set to true, the FlowerNode is ignored and skipped */
     disabled?: boolean;
 };

package/dist/src/components/types/FlowerComponent.d.ts

@@ -1,4 +1,6 @@
 export type FlowerComponentProps = {
+    /** The name of the component */
     name: string;
+    /** The component's children */
     children: React.ReactNode;
 };

package/dist/src/components/types/FlowerField.d.ts

@@ -1,30 +1,108 @@
 import { FunctionRule, RulesObject } from '@flowerforce/flower-core';
 export type FlowerFieldProps<T extends Record<string, any> = Record<string, any>> = {
+    /** The path to the value you want to read from the flow's data
+     *
+     * Example: id="loginForm.name"
+     *
+     * The FlowerField component reads the value of the key "name" of the loginForm object in the flow's data
+     */
     id?: string;
+    /** The FlowerField's children  */
     children: React.ReactNode | ((props: {
+        /** The string passed to the "id" FlowerField's prop */
         id: string;
+        /** The value found at the "id" key in the flow data
+         *
+         * Example: id="loginForm.name"
+         *
+         * This parameter will hold the value found at the key 'name' of the loginForm object in the flow's data.
+         */
         value: any;
+        /** An array of strings containing error messages associated with validation rules that are not satisfied. */
         errors: undefined | string[];
+        /** This parameter will notify you when there are validation errors. */
         hasError: undefined | boolean;
+        /** Use this function to write a new value at the "id" key
+         *
+         * Example: id="loginForm.name"
+         *
+         * onChange("John") will write "John" at the key 'name' of the loginForm object in the flow's data.
+         */
         onChange: (props: any) => void;
+        /** The function executed to test all the validation rules*/
         onBlur: () => void;
+        /** This parameter will notify you whether the form field has been touched */
         isTouched: boolean;
+        /** true when some of the display rules are not satisfied, and you have passed true to the "alwaysDisplay" FlowerField's prop*/
         hidden: boolean;
+        /** true when you have an async validation in progress */
         isValidating: boolean | undefined;
     }) => React.ReactNode | React.ReactElement | undefined);
+    /**The validation rules for that field
+     *
+     *  Example: validate={[
+     *
+     *       {
+     *           rules: {
+     *             $self: {
+     *               $regex:
+     *                 '^([A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST]{1}[0-9LMNPQRSTUV]{2}[A-Z]{1}[0-9LMNPQRSTUV]{3}[A-Z]{1})$|([0-9]{11})$',
+     *             },
+     *           },
+     *           message: 'Value not valid',
+     *        },
+     *        {
+     *          // Don't use promises
+     *          rules: (data)=> {
+     *            return data.name === 'Andrea'
+     *          },
+     *          message: 'Value not valid',
+     *        }
+     *       ]}
+     *
+     * For every rule you can pass an error message, that Flower returns when that condition is note satisfied
+     */
     validate?: Record<string, any>[] | string[];
+    /** A function to perform an async validation */
     asyncValidate?: (value: any, data?: Record<string, any>, errors?: undefined | string[]) => string[] | undefined | Promise<string[]> | {
         message: string;
     }[] | boolean | Promise<boolean>;
+    /** Use this to set a debounce for the async validation
+     *
+     * The default value is 0
+     */
     asyncDebounce?: number;
+    /** The initial error message when you have an async validation
+     *
+     * The default value is undefined
+     */
     asyncInitialError?: string;
+    /** The message that the FlowerField returns while validating*/
     asyncWaitingError?: string;
+    /** An object containing the display rules of that component. When the conditions are not satisfied, the children is hidden.
+     *
+     * Example: rules={{ $and: [{ name: { $exist: true } }] }}
+     */
     rules?: RulesObject<T> | FunctionRule;
+    /** The name of the flow from which read the data
+     *
+     * - note: the default value is the name of the flow where the component is used
+     */
     flowName?: string;
+    /** Initial value field */
     defaultValue?: unknown;
     destroyValue?: boolean;
     value?: any;
+    /** When set to true, the children is shown even if the rules are not satisfied
+     *
+     * The FlowerField returns the boolean variable "hidden" to notify you if the conditions are satisfied or not
+     */
     alwaysDisplay?: boolean;
+    /** The function executed when the value found at the path passed to the "id" prop changes */
     onUpdate?: (value: any) => void;
+    /** The function executed at the "onBlur" event, for example for Input components
+     *
+     * The onBlur function will test all the validation rules
+     */
     onBlur?: (e: any) => void;
 };

package/dist/src/components/types/FlowerFlow.d.ts

@@ -1,4 +1,14 @@
 import { FlowerNodeDefaultProps } from './DefaultNode';
 export type FlowerFlowProps = FlowerNodeDefaultProps & {
+    /** A Flower node is visible only when is the current node in the navigation history of the flow.
+     *
+     * By setting this prop to true, you have the ability to view this node even when it is not the current node.
+     *
+     * This can only be set to true for FlowerNode and FlowerFlow components.
+     *
+     * An example use case is when transitioning from a FlowerNode containing a particular screen to an action node.
+     *
+     * The node with retain set to true will continue to be displayed until a new FlowerNode or FlowerFlow is added to the history
+     * */
     retain?: boolean;
 };

package/dist/src/components/types/FlowerHooks.d.ts

@@ -3,25 +3,48 @@ export type UseFlowerProps = {
     [x in 'name' | 'flowName']?: string;
 };
 export type UseFlowerForm = (options?: UseFlowerProps) => {
+    /**  This value is set to true when the form has been touched at least once. */
     touched: boolean;
+    /** An object containing all the form errors */
     errors: Record<string, any>;
+    /** This value is set to true when all the validation rules are satisfied and the form is valid*/
     isValid: boolean;
+    /** This value is set to true during asynchronous validation.*/
     isValidating: boolean | undefined;
+    /** Use this function to read values from the flow's data. */
     getData: (path?: string) => any;
-    setData: (value: any, path?: string) => void;
-    unsetData: (path: string) => void;
+    /** Use this function to set values in the flow's data. */
+    setData: (
+    /** The value that you want to set */
+    value: any, 
+    /** Specify the target path to set the value*/
+    path?: string) => void;
+    /** Use this function to unset values in the flow's data. */
+    unsetData: (
+    /** Specify the target path to the value tha you want to unset*/
+    path: string) => void;
+    /** Use this function to replace a value in the flow's data. */
     replaceData: (value: any) => void;
 };
 type useFlowerActions = {
+    /** Use this function to move to the next node inside the flow*/
     next: (payload?: Route) => void;
+    /**Use this function to move to the previous node inside the flow*/
     back: (payload?: RoutePrev) => void;
+    /**Use this function to return to the first node and restore history */
     reset: (payload?: RouteReset) => void;
+    /**Use this function to move to a specific node*/
     jump: (payload: RouteNode) => void;
+    /**Use this function to reset the flow data and history */
     restart: (payload?: RouteRestart) => void;
 };
 export type UseFlower = (options?: UseFlowerProps) => useFlowerActions & {
+    /**The flow in which the hook is used.*/
     flowName?: string;
+    /**Current node id*/
     nodeId: string;
+    /**Initial start node id*/
+    startId: string;
 };
 export type NavigateFunctionParams = string | Record<string, any>;
 export {};

package/dist/src/components/types/FlowerNavigate.d.ts

@@ -3,6 +3,10 @@ export type Route = string | Record<string, any>;
 export type RouteNode = string | {
     node: string;
     flowName?: string;
+    /**
+     * The flow's history on server component
+     * @experimental
+     */
     history?: string[];
 };
 export type RouteRestart = string | {
@@ -19,9 +23,19 @@ export type RoutePrev = string | {
     flowName?: string;
 };
 export type FlowerNavigateProps = {
+    /** The name of the flow from which read the data
+     *
+     * - note: the default value is the name of the flow where the component is used
+     */
     flowName?: string | undefined;
+    /** The FlowerNavigate's children  */
     children: React.ReactNode | ((props: Record<string, any>) => React.ReactNode | React.ReactElement | undefined);
+    /** An object containing the display rules of that component. When the conditions are not satisfied, the children is hidden. */
     rules?: RulesObject<Record<string, any>> | Record<string, RulesObject<any>>;
+    /** When set to true, the children is shown even if the rules are not satisfied
+     *
+     * The FlowerValue returns the boolean variable "hidden" to notify you if the conditions are satisfied or not
+     */
     alwaysDisplay?: boolean;
 } & ({
     action?: 'next';

package/dist/src/components/types/FlowerNode.d.ts

@@ -1,4 +1,14 @@
 import { FlowerNodeDefaultProps } from './DefaultNode';
 export type FlowerNodeProps = FlowerNodeDefaultProps & {
+    /** A Flower node is visible only when is the current node in the navigation history of the flow.
+     *
+     * By setting this prop to true, you have the ability to view this node even when it is not the current node.
+     *
+     * This can only be set to true for FlowerNode and FlowerFlow components.
+     *
+     * An example use case is when transitioning from a FlowerNode containing a particular screen to an action node.
+     *
+     * The node with retain set to true will continue to be displayed until a new FlowerNode or FlowerFlow is added to the history
+     * */
     retain?: boolean;
 };

package/dist/src/components/types/FlowerRoute.d.ts

@@ -1,8 +1,25 @@
 export type FlowerRouteProps = {
+    /** Unique identifier for the node inside the Flow */
     id: string;
+    /** TODO document what this props does */
     autostart?: boolean;
+    /** An object containing the informations about the node's links.
+     *
+     * Example: to={{ step2: { rules: { $and: [{ name: { $eq: 'John' } }] } } }}
+     *
+     * In that case, the FlowerRoute is linked to the node with the ID 'step2'
+     *
+     * You can move from the current node to the step2 node only if the rules are satisfied
+     *
+     * Set it to null when you don't have rules
+     *
+     * Example: to={{ step2: null}
+     */
     to?: Record<string, any>;
+    /** The children of the FlowerRoute */
     children?: React.ReactNode;
+    /** The function executed when you enter into this FlowerRoute */
     onEnter?: () => void;
+    /** The function executed when you leave this FlowerRoute */
     onExit?: () => void;
 };

package/dist/src/components/types/FlowerRule.d.ts

@@ -1,11 +1,34 @@
 import { FunctionRule, RulesObject } from '@flowerforce/flower-core';
 export type FlowerRuleProps = {
+    /** The path to the value you want to read from the flow's data
+     *
+     * Example: id="loginForm.name"
+     *
+     * The FlowerRule component reads the value of the key "name" of the loginForm object in the flow's data
+     */
     id?: string;
+    /** */
     value?: any;
+    /** An object or function containing the display rules of that component. When the conditions are not satisfied, the children is hidden.
+     *
+     * Example: rules={{ $and: [{ name: { $exist: true } }] }}
+     * Example: rules={(state) => state... === true}
+     * if missing it is always visible
+     */
     rules?: RulesObject<any> | FunctionRule;
+    /** The name of the flow from which read the data
+     *
+     * - note: the default value is the name of the flow where the component is used
+     */
     flowName?: string;
+    /** When set to true, the children is shown even if the rules are not satisfied
+     *
+     * The FlowerRule returns the boolean variable "hidden" to notify you if the conditions are satisfied or not
+     */
     alwaysDisplay?: boolean;
+    /** The function executed when the value found at the path passed to the "id" prop changes */
     onUpdate?: (hidden: boolean) => void;
+    /** The children of the FlowerRule*/
     children?: React.ReactNode | ((props: {
         hidden?: boolean;
     }) => React.ReactNode | React.ReactElement | undefined);

package/dist/src/components/types/FlowerServer.d.ts

@@ -1,7 +1,9 @@
 import { FlowerNodeProps } from './FlowerNode';
 export type FlowerServerProps = {
     action?: {
+        /** The type of the action */
         type: string;
+        /** The parameters passed to the action */
         props?: Record<string, any>;
     };
 } & FlowerNodeProps;

package/dist/src/components/types/FlowerValue.d.ts

@@ -1,11 +1,33 @@
 import { FunctionRule, RulesObject } from '@flowerforce/flower-core';
 export type FlowerValueProps = {
+    /** The path to the value you want to read from the flow's data
+     *
+     * Example: id="loginForm.name"
+     *
+     * The FlowerValue component reads the value of the key "name" of the loginForm object in the flow's data
+     * If missing, I return all values, which is equivalent to setting id='*'
+     */
     id?: string;
     value?: any;
+    /** An object containing the display rules of that component. When the conditions are not satisfied, the children is hidden.
+     *
+     * Example: rules={{ $and: [{ name: { $exist: true } }] }}
+     */
     rules?: RulesObject<any> | FunctionRule;
+    /** The FlowerValue's children  */
     children: React.ReactNode | ((props: Record<string, any>) => React.ReactNode | React.ReactElement | undefined);
+    /** Set this value to true to spread the value into separate values in case it is an object. */
     spreadValue?: boolean;
+    /** The name of the flow from which read the data
+     *
+     * - note: the default value is the name of the flow where the component is used
+     */
     flowName?: string;
+    /** When set to true, the children is shown even if the rules are not satisfied
+     *
+     * The FlowerValue returns the boolean variable "hidden" to notify you if the conditions are satisfied or not
+     */
     alwaysDisplay?: boolean;
+    /** The function executed when the value found at the path passed to the "id" prop changes */
     onUpdate?: (value: any) => void;
 };

package/dist/src/components/useFlower.d.ts

@@ -1,3 +1,21 @@
 import { UseFlower } from './types/FlowerHooks';
+/** This hook allows you to read flow informations, such as the flowName and ID of the current node.
+ *
+ * It also exposes all the functions to navigate within the flow:
+ *
+ * - next
+ *
+ * - back
+ *
+ * - jump
+ *
+ * - reset
+ *
+ * - restart
+ *
+ * @param {string} flowName - first optional parameter
+ *
+ * @param {string} name - optional parameter, if flowName exist, name is not used
+ */
 declare const useFlower: UseFlower;
 export default useFlower;

package/dist/src/components/useFlowerForm.d.ts

@@ -1,3 +1,20 @@
 import { UseFlowerForm } from './types/FlowerHooks';
+/**  This hook allows you to manage and retrieve information about Forms.
+ *
+ * It exposes details regarding the form's state and a set of methods for reading and writing within it:
+ *
+ * - getData
+ *
+ * - setData
+ *
+ * - unSetData
+ *
+ * - replaceData
+ *
+ * @param {string} flowName - first optional parameter
+ *
+ * @param {string} name - optional parameter, if flowName exist, name is not used
+ *
+ */
 declare const useFlowerForm: UseFlowerForm;
 export default useFlowerForm;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowerforce/flower-react",
-  "version": "3.1.1",
+  "version": "3.1.2-beta.1",
   "description": "FlowerJS components, hooks and utils for React.",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "@flowerforce/flower-core": "3.1.1",
+    "@flowerforce/flower-core": "*",
     "@reduxjs/toolkit": "^2.2.4",
     "lodash": "^4.17.21",
     "react-redux": "^9.1.2",