Merge pull request #27 from iusehooks/ADD_INNER_REF_AND_SETVALUE_CUST…

…OM_CMP

innerRef - setValue for type='custom'

__tests__/Form.spec.js

@@ -1,5 +1,11 @@
 import React from "react";
-import { render, cleanup, fireEvent, waitFor } from "@testing-library/react";
+import {
+  render,
+  cleanup,
+  fireEvent,
+  waitFor,
+  act
+} from "@testing-library/react";
 
 import { SimpleFormTestSumbission } from "./helpers/components/SimpleFormTestSumbission";
 import { CollectionDynamicCart } from "./helpers/components/CollectionDynamicField";
@@ -12,7 +18,7 @@ import {
 } from "./helpers/components/ComplexForm";
 import { mountForm } from "./helpers/utils/mountForm";
 
-import { Input, Select, Collection, TextArea } from "./../src";
+import { Input, Select, Collection, TextArea, Form } from "./../src";
 
 const dataTestid = "email";
 const typeInput = "text";
@@ -514,6 +520,18 @@ describe("Component => Form", () => {
     );
   });
 
+  it("should accept an innerRef prop to access to DOM", () => {
+    const name = "foo";
+    const ref = React.createRef();
+
+    act(() => {
+      render(<Form innerRef={ref} name={name} />);
+    });
+
+    expect(ref.current).toBeDefined();
+    expect(ref.current.name).toBe(name);
+  });
+
   it("should run reducer functions applied to Form on fields removal", () => {
     const reducers = jest.fn(value => {
       const { cart = {} } = value;

__tests__/Input.spec.js

@@ -180,6 +180,23 @@ describe("Component => Input", () => {
     expect(fileInputMultiple.files[1]).toStrictEqual(files[1]);
   });
 
+  it("should accept an innerRef prop to access to DOM", () => {
+    const type = "text";
+    const name = "email";
+    const ref = React.createRef();
+    const children = [
+      <Input key="1" innerRef={ref} type={type} name={name} value="1" />
+    ];
+    act(() => {
+      mountForm({ children });
+    });
+
+    expect(ref.current).toBeDefined();
+    expect(ref.current.type).toBe(type);
+    expect(ref.current.value).toBe("1");
+    expect(ref.current.name).toBe(name);
+  });
+
   it("should trigger onChange event when the Input value changes", () => {
     const onChangeInput = jest.fn(value => value);
     const children = [
@@ -518,11 +535,7 @@ describe("Component => Input", () => {
     expect(checkbox.checked).toBe(true);
 
     onInit.mockClear();
-    children = [<Input key="1" type="custom" name={name} value={{ a: 1 }} />];
-    mountForm({ props, children });
-    expect(onInit).toHaveBeenCalledWith({ [name]: { a: 1 } }, true);
 
-    onInit.mockClear();
     children = [
       <Input
         key="1"

__tests__/Select.spec.js

@@ -126,6 +126,26 @@ describe("Component => Select", () => {
     expect(onReset).toHaveBeenCalledWith({ [name]: ["1", "2"] }, true);
   });
 
+  it("should accept an innerRef prop to access to DOM", () => {
+    const name = "test";
+    const value = "1";
+    const ref = React.createRef();
+    const children = [
+      <Select key="1" innerRef={ref} name={name} value={value}>
+        <option value="" />
+        <option value={value}>{value}</option>
+      </Select>
+    ];
+
+    act(() => {
+      mountForm({ children });
+    });
+
+    expect(ref.current).toBeDefined();
+    expect(ref.current.value).toBe("1");
+    expect(ref.current.name).toBe(name);
+  });
+
   it("should use a reducer to reduce the Select value", () => {
     const props = { onInit };
     const reducer = value => value + 2;

__tests__/TextArea.spec.js

@@ -1,5 +1,5 @@
 import React from "react";
-import { fireEvent, cleanup } from "@testing-library/react";
+import { fireEvent, cleanup, act } from "@testing-library/react";
 import { mountForm } from "./helpers/utils/mountForm";
 import { TextArea } from "./../src";
 
@@ -29,4 +29,22 @@ describe("Component => TextArea", () => {
     expect(onChange).toHaveBeenCalledWith({ [name]: value }, true);
     expect(textArea.value).toBe(value);
   });
+
+  it("should accept an innerRef prop to access to DOM", () => {
+    const type = "textarea";
+    const name = "foo";
+    const ref = React.createRef();
+    const children = [
+      <TextArea key="1" innerRef={ref} name={name} value="1" />
+    ];
+
+    act(() => {
+      mountForm({ children });
+    });
+
+    expect(ref.current).toBeDefined();
+    expect(ref.current.type).toBe(type);
+    expect(ref.current.value).toBe("1");
+    expect(ref.current.name).toBe(name);
+  });
 });

__tests__/helpers/components/CustomField.jsx

@@ -10,7 +10,13 @@ export const CustomField = withIndex(
     valueToChange = "5"
   }) => {
     const props = useField({ type, name, value });
-    const onChange = () => props.onChange({ target: { value: valueToChange } });
+    const onChange = () => {
+      if (type === "custom") {
+        props.setValue(valueToChange);
+      } else {
+        props.onChange({ target: { value: valueToChange } });
+      }
+    };
     useEffect(() => {
       jestFN(props.value);
     }, []);

__tests__/hooks/useField.spec.js

@@ -55,9 +55,18 @@ describe("Hooks => useField", () => {
     const props = { onInit, onChange };
     const initial = { a: "test" };
     const jestFN = jest.fn();
+    const valueToChange = prev => {
+      return { ...prev, a: "BeBo" };
+    };
 
     const children = [
-      <CustomField key="1" name={name} value={initial} jestFN={jestFN} />
+      <CustomField
+        key="1"
+        valueToChange={valueToChange}
+        name={name}
+        value={initial}
+        jestFN={jestFN}
+      />
     ];
     const { getByTestId } = mountForm({ children, props });
 
@@ -70,7 +79,7 @@ describe("Hooks => useField", () => {
       fireEvent.click(buttonChange);
     });
 
-    expect(onChange).toHaveBeenCalledWith({ [name]: "5" }, true);
+    expect(onChange).toHaveBeenCalledWith({ [name]: { a: "BeBo" } }, true);
   });
 
   it("should render a Field of type text with an initial value passed as prop", () => {

docs/Collection.mdx

@@ -14,7 +14,7 @@ import { Collection, useValidation, Input, useAsyncValidation } from './../src';
 It creates a nested piece of state within a Form. <br />
 A Collection can be of type: **object** or **array**.
 
-### Props
+## Props
 
 **`object`**: boolean
 
@@ -24,13 +24,15 @@ It creates a collecion of type **object** if "true".
 
 It creates a collecion of type **array** if "true".
 
-**`name`**: string - (except for **Collection** children of Collection of type array)
+**`name`**: string
 
-A field's name in Usetheform state.
+A field's name in Usetheform state. <br />
+If your Collection is rendered within a `<Collection array />`, **name** is not allowed as prop.
 
-**`index`**: string - (only for **Collection** children of Collection of type array)
+**`index`**: string
 
-A field's index in array Collection.
+A field's index in array Collection. <br />
+**index** is only allowed If your Collection is rendered within a `<Collection array /> `. 
 
 **`touched`**: boolean
 

docs/Form.mdx

@@ -10,7 +10,7 @@ import { Input } from './../src';
 # Form
 The Form is the most important component in Usetheform. It renders all the Fields and keeps synchronized the entire form state.
 
-### Props
+## Props
 
 **`onInit`**: function
 
@@ -81,6 +81,15 @@ Possible values:
  - An absolute URL - points to another web site (like action="http://www.example.com/example.htm")
  - A relative URL - points to a file within a web site (like action="example.htm")
 
+**`innerRef`**: object (a mutable ref object)
+
+When you need to access the underlying DOM node created by Form (e.g. to call focus), you can use a ref to store a reference to the form dom node.
+
+```javascript
+const ref = useRef(null)
+<Form innerRef={ref} name="form">...fields...</Form>
+```
+
 ## Basic usage
 
 ### Example 1

docs/FormContext.mdx

@@ -11,7 +11,7 @@ import { Input, useForm } from './../src';
 
 It is a react component that provides a context of the "form" at wider level.
 
-### Props
+## Props
 
 **`onInit`**: function
 

docs/Input.mdx

@@ -11,19 +11,21 @@ import { Input, useValidation, useAsyncValidation } from './../src';
 # Input
 It renders all the inputs of type listed at: [W3schools Input Types](https://www.w3schools.com/html/html_form_input_types.asp) and accepts as props any html attribute listed at: [Html Input Attributes](https://www.w3schools.com/tags/tag_input.asp).
 
-### Props
+## Props
 
 **`type`**: string
 
 Type listed at: [W3schools Input Types](https://www.w3schools.com/html/html_form_input_types.asp).
 
-**`name`**: string - (except for **Input** children of Collection of type array)
+**`name`**: string
 
-A field's name in Usetheform state.
+A field's name in Usetheform state. <br />
+If your Input is rendered within a `<Collection array />`, **name** is not allowed as prop.
 
-**`index`**: string - (only for **Input** children of Collection of type array)
+**`index`**: string
 
-A field's index in array Collection.
+A field's index in array Collection. <br />
+**index** is only allowed If your Input is rendered within a `<Collection array /> `. 
 
 **`value`**: string | number
 
@@ -48,6 +50,15 @@ If *true* validation messages (sync and async) will be showing only when the eve
 An array whose values correspond to different reducing functions.
 Reducers functions specify how the Input's value change.
 
+**`innerRef`**: object (a mutable ref object)
+
+When you need to access the underlying DOM node created by Input (e.g. to call focus), you can use a ref to store a reference to the input dom node.
+
+```javascript
+const ref = useRef(null)
+<Input innerRef={ref} type="text" name="test" />
+```
+
 ## Basic usage
 
 ```javascript

docs/Select.mdx

@@ -12,15 +12,17 @@ import { Select, useValidation, useAsyncValidation } from './../src';
 The *select* element is used to create a drop-down list. <br />
 It accepts as props any html attribute listed at: [Html Select Attributes](https://www.w3schools.com/tags/tag_select.asp).
 
-### Props
+## Props
 
-**`name`**: string - (except for **Select** children of Collection of type array)
+**`name`**: string
 
-A field's name in Usetheform state.
+A field's name in Usetheform state. <br />
+If your Select is rendered within a `<Collection array />`, **name** is not allowed as prop. 
 
-**`index`**: string - (only for **Select** children of Collection of type array)
+**`index`**: string
 
-A field's index in array Collection.
+A field's index in array Collection. <br />
+**index** is only allowed If your Select is rendered within a `<Collection array /> `.
 
 **`value`**: string
 
@@ -32,6 +34,10 @@ A field that has been touched/visited. Default value *false*.
 
 If *true* validation messages (sync and async) will be showing only when the event onBlur of the field is triggered by the user action.
 
+**`multiple`**: boolean
+
+When present, it specifies that multiple options can be selected at once. Default value *false*. 
+
 **`reducers`**: array | function
 
 ```javascript
@@ -41,6 +47,15 @@ If *true* validation messages (sync and async) will be showing only when the eve
 An array whose values correspond to different reducing functions.
 Reducers functions specify how the Select's value change.
 
+**`innerRef`**: object (a mutable ref object)
+
+When you need to access the underlying DOM node created by Select (e.g. to call focus), you can use a ref to store a reference to the select dom node.
+
+```javascript
+const ref = useRef(null)
+<Select innerRef={ref} name="test">...options...</Select>
+```
+
 ## Basic usage 
 
 ### Single options

docs/TextArea.mdx

@@ -11,15 +11,17 @@ import { TextArea, useValidation, useAsyncValidation } from './../src';
 # TextArea
 It renders a *textarea* element: [W3schools Textarea](https://www.w3schools.com/tags/tag_textarea.asp) and accepts as props any html attribute listed at: [Html Textarea Attributes](https://www.w3schools.com/tags/tag_textarea.asp).
 
-### Props
+## Props
 
-**`name`**: string - (except for **TextArea** children of Collection of type array)
+**`name`**: string
 
-A field's name in Usetheform state.
+A field's name in Usetheform state. <br />
+If your TextArea is rendered within a `<Collection array />`, **name** is not allowed as prop.
 
-**`index`**: string - (only for **TextArea** children of Collection of type array)
+**`index`**: string
 
-A field's index in array Collection.
+A field's index in array Collection. <br />
+**index** is only allowed If your TextArea is rendered within a `<Collection array /> `.
 
 **`value`**: string
 
@@ -40,6 +42,15 @@ If *true* validation messages (sync and async) will be showing only when the eve
 An array whose values correspond to different reducing functions.
 Reducers functions specify how the TextArea's value change.
 
+**`innerRef`**: object (a mutable ref object)
+
+When you need to access the underlying DOM node created by TextArea (e.g. to call focus), you can use a ref to store a reference to the textarea dom node.
+
+```javascript
+const ref = useRef(null)
+<TextArea innerRef={ref} name="textarea" value="test" />
+```
+
 ## Basic usage
 
 ```javascript