Skip to content

Commit aebf561

Browse files
danielopradodanieloprado
committed
Docs update
Signed-off-by: danieloprado <danielprado.ad@gmail.com>
1 parent e8593c0 commit aebf561

8 files changed

Lines changed: 251 additions & 93 deletions

File tree

‎API.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# API
2+
3+
* [Validation Rules](#validation-rules)
4+
* [Components](#components)
5+
* [CustomMessage](#custommessage)
6+
* [ValidationContext](#validationcontext)
7+
* [Interfaces](#interfaces)
8+
* [IPropsFieldBase](#ipropsfieldbase)
9+
* [Hooks](#hooks)
10+
* [useMask](#useMask)
11+
* [useValidation](#useValidation)
12+
13+
## Validation Rules
14+
15+
See [validatorjs](https://github.com/skaterdav85/validatorjs#available-rules) rules
16+
17+
## Components
18+
19+
### CustomMessage
20+
21+
Used to override a validation message, this will not output anything, just will change the default message of an error.
22+
23+
| Props | Required | Type | Description |
24+
| -------- | -------- | ----------------------------- | ------------------------------------------- |
25+
| rules | true | string | Rules separeted by common. Ex: required,min |
26+
| children | true | ReactNode (string, jsx e etc) | The new validation message |
27+
28+
Example:
29+
```jsx
30+
<YourFieldWithUseValidation>
31+
<CustomMessage rules='required'>Hey, this is required</CustomMessage>
32+
</YourFieldWithUseValidation>
33+
```
34+
35+
### ValidationContext
36+
37+
Used to control and check a group of fields.
38+
39+
| Props | Required | Type | Description |
40+
| ----- | -------- | ---- | ----------- |
41+
| none | | | |
42+
43+
| Methods | Return | Description |
44+
| -------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
45+
| isValid(formSubmitted: boolean = true) | boolean | Check if all fiels are valid and set form as submitted or not |
46+
| reset() | nothing/void | reset the state of form submission and all field are cleanup (dirty false), will not change any value of your model/state |
47+
48+
Example:
49+
```tsx
50+
import ValidationContext, { IValidationContextRef } from '@react-form-fields/core/components/ValidationContext';
51+
52+
const App = () => {
53+
const validationContextRef = useRef<IValidationContextRef>();
54+
55+
//your form submission...
56+
validationContextRef.current.isValid();
57+
//....
58+
59+
//your form reset...
60+
validationContextRef.current.reset();
61+
//....
62+
63+
return (
64+
<ValidationContext ref={validationContextRef}>
65+
<YourFieldWithUseValidation/>
66+
<YourFieldWithUseValidation/>
67+
<YourFieldWithUseValidation/>
68+
</ValidationContext>
69+
);
70+
}
71+
```
72+
73+
## Interfaces
74+
75+
### IPropsFieldBase
76+
77+
Props Base to create a form field component.
78+
import from: @react-form-fields/core/interfaces/props
79+
80+
| Props | Required | Type | Description |
81+
| ------------------------ | -------- | ---------------------- | ---------------------------------------------------------------------- |
82+
| name | false | string | |
83+
| value | false | any | |
84+
| submitted | false | boolean | flag to set if form was submited (also can be set by setFormSubmitted) |
85+
| validation | false | string | rules of validation |
86+
| validationContext | false | object { prop: value } | extra fields for validation bind (ex. required_if) |
87+
| validationAttributeNames | false | object { prop: value } | see: https://github.com/skaterdav85/validatorjs#custom-attribute-names |
88+
| errorMessage | false | string | custom error message from external validation |
89+
90+
## Hooks
91+
92+
### useMask
93+
94+
| Result Props | Type | Description |
95+
| ------------ | -------- | ------------------------- |
96+
| maskApply | Function | apply current mask |
97+
| maskClean | Function | clean current mask |
98+
| maskedValue | string | value with mask applied |
99+
| cleanedValue | string | value withou mask applied |
100+
101+
### useValidation
102+
103+
| Result Props | Type | Description |
104+
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
105+
| isValid | boolean | if the field is valid or not |
106+
| errorMessage | string | current error message |
107+
| showError | boolean | if component should show the error message, true if form submitted or is field is dirty or errorMessage prop was pass |
108+
| dirty | boolean | if the field was changed by your component |
109+
| setDirty | Function | function to set if value was changed by your component |
110+
| submitted | boolean | if form was submitted |

‎HOW_TO_USE.md‎

Lines changed: 104 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,131 @@
11
# How To Use
22

3-
### Base (Common props)
3+
See [API.md](https://github.com/react-form-fields/core/blob/master/API.md) to see all configs available
44

5-
Component Base to create a form field.
5+
* [How to Create a Form Field](#how-to-create-a-form-field)
6+
* [How to a custom validation rules](#how-to-a-custom-validation-rules)
7+
* [How extends default config](#how-extends-default-config)
8+
* [How to create or extends a language config](#how-to-create-or-extends-a-language-config)
69

7-
| Props | Required | Type | Description |
8-
|--------------------------|----------|------------------------|------------------------------------------------------------------------|
9-
| name | false | string | |
10-
| value | false | any | |
11-
| submitted | false | boolean | flag to set if form was submited (also can be set by setFormSubmitted) |
12-
| validation | false | string | rules of validation |
13-
| validationContext | false | object { prop: value } | extra fields for validation bind (ex. required_if) |
14-
| validationAttributeNames | false | object { prop: value } | see: https://github.com/skaterdav85/validatorjs#custom-attribute-names |
15-
| errorMessage | false | string | custom error message from external validation |
16-
17-
### How to Create a Form Field
10+
## How to Create a Form Field
1811

1912
```tsx
20-
import FieldCoreBase, { IPropsFieldBase, IStateFieldBase } from '@react-form-fields/core/components/FieldCoreBase';
21-
22-
interface IState extends IStateFieldBase { //<-- extends
23-
//your state props
13+
import useMask from '@react-form-fields/core/hooks/useMask';
14+
import useValidation from '@react-form-fields/core/hooks/useValidation';
15+
import { IPropsFieldBase } from '@react-form-fields/core/interfaces/props';
16+
import React, { useCallback } from 'react';
17+
18+
interface IProps extends IPropsFieldBase { // <~extends your interface props from IPropsFieldBase
19+
placeholder: string;
20+
value: string;
21+
onChange(value: string): void;
2422
}
2523

26-
interface IProps extends IPropsFieldBase { //<-- extends
27-
// your props
28-
onChange: (value: string) => void;
29-
}
24+
const Field = React.memo((props: IProps) => {
25+
const { onChange, placeholder } = props;
26+
27+
const { errorMessage, showError, setDirty } = useValidation(props); // <~ Register your field and get validation
28+
const { maskedValue, maskClean } = useMask(props); // <~ (optional) get the mask info, don't worry if no mask was pass, there is a default
29+
30+
const onChangeHandler = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
31+
setDirty(true); // <~ remember to check your field as dirty
32+
onChange(maskClean(e.currentTarget.value) as string); // <~ (optional) always pass the "clean" value
33+
}, [onChange, setDirty, maskClean]);
34+
35+
return (
36+
<div className='input-container'>
37+
<input
38+
type='text'
39+
placeholder={placeholder}
40+
value={maskedValue} // <~ (optional) use the masked value
41+
onChange={onChangeHandler}
42+
/>
43+
44+
{showError && errorMessage && // <~ use showError to know when the error message should be display
45+
<p className='error'>{errorMessage}</p>
46+
}
47+
</div>
48+
)
49+
});
50+
51+
export default Field;
52+
```
3053

31-
class MyComponentField extends FieldCoreBase<IProps, IState> {
32-
//[optional] If you need getDerivedStateFromProps dont forget to call super
33-
static getDerivedStateFromProps(props: IProps, currentState: IState): IState {
34-
const state = super.getDerivedStateFromProps(props, currentState);
35-
// your logic....
36-
return state;
37-
}
54+
## How to a custom validation rules
3855

39-
onChange = event => {
40-
const value = this.mask.clean(event.target ? event.target.value : event);
56+
See [validatorjs](https://github.com/skaterdav85/validatorjs#register-custom-validation-rules)
4157

42-
this.setState({ touched: true }); //<-- important to show the error
43-
this.props.onChange(value);
44-
}
58+
## How extends default config
4559

46-
render() {
47-
const { label, name } = this.props;
48-
49-
return (
50-
<Fragment>
51-
{/* import: register the field in the validation context */}
52-
<ValidationContextRegister field={this} />
53-
54-
{/* isRequired: check if validation prop contains the required rule */}
55-
<label>{label} {this.isRequired ? '*' : ''}</label>
56-
<input
57-
name={name}
58-
value={this.getMaskedValue}
59-
onChange={this.onChange}
60-
/>
61-
62-
{/* errorMessage will be null if submitted and touched are false */}
63-
{this.errorMessage ? <p class="error">{this.errorMessage}</p> : null}
64-
</Fragment>
65-
);
66-
}
67-
}
68-
```
60+
We recommend you to always create these files to avoid imports from **@react-form-fields/core**
61+
directly, you can copy and paste initially.
6962

70-
### How extends default config
63+
Create config/context.tsx
7164

72-
```ts
73-
// your config/index.ts
74-
import * as coreConfig from '@react-form-fields/core/config';
65+
```tsx
66+
import FieldValidationConfigContextCore, { IConfig as IConfigCore } from '@react-form-fields/core/config';
67+
import ConfigBuilderClass from './builder';
7568

76-
declare module '@react-form-fields/core/config' {
77-
interface IConfig {
78-
newProps?: string;
79-
}
69+
export interface IConfig extends IConfigCore {
70+
myNewBrandConfigProp?: string; // <~ all configs are optional
8071
}
8172

82-
const defaultConfig: coreConfig.IConfig = {
83-
newProps: 'teste'
84-
};
85-
86-
export function getConfig(): coreConfig.IConfig {
87-
return {
88-
...defaultConfig,
89-
...(coreConfig.getConfig() || {})
90-
};
91-
}
73+
export const ConfigBuilder = ConfigBuilderClass;
74+
export default FieldValidationConfigContext = FieldValidationConfigContextCore;
75+
```
9276

93-
export function setConfig(config: coreConfig.IConfig) {
94-
coreConfig.setConfig(config);
95-
}
77+
Create config/builder.tsx
9678

97-
// your config/builder.ts
98-
import { IConfig } from '@react-form-fields/core/config';
79+
```tsx
9980
import CoreConfigBuilder from '@react-form-fields/core/config/builder';
81+
import { IConfig } from './context';
10082

10183
export default class ConfigBuilder extends CoreConfigBuilder {
102-
public setNewProps(newProps: string) {
84+
public setMyNewBrandConfigProp(myNewBrandConfigProp: string) {
10385
this.config = {
104-
...this.config,
105-
newProps: newProps
86+
...this.config, // <~ keeps already set's configs
87+
myNewBrandConfigProp
10688
};
10789

108-
return this; // <-- always return this
90+
return this; // <~ always return this
91+
}
92+
93+
public clean() { // <~you can override the celan method to add you own default values
94+
return {
95+
...super.clean(),
96+
myNewBrandConfigProp: 'my default value'
97+
}
10998
}
11099
}
111-
```
100+
```
101+
102+
## How to create or extends a language config
103+
104+
Create you lang file in langs/your-lang.ts
105+
106+
```ts
107+
import { IConfig } from '.../config/context';
108+
import coreLangPTBR from '@react-form-fields/core/lang/pt-br'; // <~ import original lang config
109+
import * as locale from 'date-fns/locale/pt-BR';
110+
111+
const langPTBR: IConfig = {
112+
...coreLangPTBR, // <~ extends the original lang config
113+
// add your configs
114+
myNewBrandConfigProp: 'default value for the lang',
115+
masks: [
116+
...coreLangPTBR.masks
117+
// your masks
118+
],
119+
validations: {
120+
lang: 'you-new-lang',
121+
customMessages: {
122+
...coreLangPTBR.validations.customMessages
123+
// override the default messages
124+
}
125+
}
126+
};
127+
128+
export default langPTBR;
129+
```
130+
131+
## How to

‎README.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ React Form Fields: Core
55

66
## Requirements
77

8-
* React >= 16.3.0
8+
* React >= 16.8.0 ~> Hooks needed
99

1010
## Install
1111

@@ -21,10 +21,15 @@ yarn add @react-form-fields/core
2121
### How to Create a Form Field
2222

2323
See [HOW_TO_USE.md](https://github.com/react-form-fields/core/blob/master/HOW_TO_USE.md) for details
24+
See [API.md](https://github.com/react-form-fields/core/blob/master/API.md) to see all configs available
2425

2526
### Common Masks
2627

27-
#### PT-BR:
28+
#### en-US:
29+
30+
* money
31+
32+
#### pt-BR:
2833

2934
* zipcode
3035
* phone

0 commit comments

Comments
 (0)