From 5b2347c47d557252168dae54519c8f495b1b09cd Mon Sep 17 00:00:00 2001 From: Welly Shen Date: Tue, 8 Dec 2020 22:27:14 +0800 Subject: [PATCH] docs: update readme --- .changeset/great-pandas-teach.md | 5 + README.md | 268 ++----------------------------- 2 files changed, 18 insertions(+), 255 deletions(-) create mode 100644 .changeset/great-pandas-teach.md diff --git a/.changeset/great-pandas-teach.md b/.changeset/great-pandas-teach.md new file mode 100644 index 00000000..4e058f4c --- /dev/null +++ b/.changeset/great-pandas-teach.md @@ -0,0 +1,5 @@ +--- +"react-cool-form": patch +--- + +docs: update readme diff --git a/README.md b/README.md index e7a50bde..e2c380b1 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -> 🚨 Under developing the API may be changed fast, **don't use it in production atm**. Please note any changes via [release](https://github.com/wellyshen/react-cool-form/releases). Here's the [milestone](#milestone). +> 🚨 Under developing the API may be changed fast, **DON'T USE IT ATM**. Please note any changes via [release](https://github.com/wellyshen/react-cool-form/releases). Here's the [milestone](#milestone). # REACT COOL FORM @@ -22,11 +22,18 @@ React hooks for forms state and validation, less code more performant. - ☁️ Server-side rendering compatibility. - 🦔 Tiny size ([~ 4.7KB gzipped](https://bundlephobia.com/result?p=react-cool-form)) but powerful. -## Getting Started +## [Docs](https://react-cool-form.netlify.app) -To use `react-cool-form`, you must use `react@16.8.0` or greater which includes hooks. +See the documentation at [react-cool-form.netlify.app](https://react-cool-form.netlify.app) for more information about using `react-cool-form`! -You can install this package via [npm](https://www.npmjs.com/package/react-cool-form). +Frequently viewed docs: + +- [Getting Started](https://react-cool-form.netlify.app/docs) +- API Reference + +## Quick Start + +To use `react-cool-form`, you must use `react@16.8.0` or greater which includes hooks. This package is distributed via [npm](https://www.npmjs.com/package/react-cool-form). ```sh $ yarn add react-cool-form @@ -34,7 +41,7 @@ $ yarn add react-cool-form $ npm install --save react-cool-form ``` -Here's the basic example of how does it works, full documentation will be provided soon. If you have any question, feel free to [ask me](https://github.com/wellyshen/react-cool-form/issues/new?template=question.md). +Here's the basic example of how does it works: [![Edit RCF - Basic](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/rcf-basic-jq93g?fontsize=14&hidenavigation=1&theme=dark) @@ -84,256 +91,7 @@ const App = () => { }; ``` -The form state of the above example will look something like this: - -```json -{ - "values": { - "name": "Welly", - "email": "hivoid19@gmail.com", - "password": "12345" - }, - "touched": { - "name": true, - "email": true, - "password": true - }, - "isValidating": false, - "isValid": false, - "errors": { - "password": "Please lengthen this text to 8 characters or more" - }, - "isDirty": true, - "dirtyFields": { - "name": true, - "email": true, - "password": true - }, - "isSubmitting": false, - "isSubmitted": false, - "submitCount": 1 -} -``` - -Super easy right? The above example is just the tip of the iceberg. `react-cool-form` is a lightweight and powerful form library. you can understand the **API** by its type definition atm to see how it rocks 🤘🏻. - -```ts -import { FocusEvent, RefObject, SyntheticEvent } from "react"; - -type FormValues = Record; - -type DeepProps = { - [K in keyof V]?: V[K] extends T ? T : DeepProps; -}; - -type Errors = DeepProps; - -type FormState = Readonly<{ - values: V; - touched: DeepProps; - errors: Errors; - isDirty: boolean; - dirtyFields: DeepProps; - isValidating: boolean; - isValid: boolean; - isSubmitting: boolean; - isSubmitted: boolean; - submitCount: number; -}>; - -type Options = Omit, "form" | "field" | "submit" | "controller">; - -interface OnReset { - ( - values: V, - options: Omit, "reset">, - event?: Event | SyntheticEvent - ): void; -} - -interface OnSubmit { - ( - values: V, - options: Options, - event?: Event | SyntheticEvent - ): void | Promise; -} - -interface OnError { - ( - errors: Errors, - options: Options, - event?: Event | SyntheticEvent - ): void; -} - -interface Debug { - (formState: FormState): void; -} - -interface FormValidator { - (values: V): Errors | void | Promise | void>; -} - -interface FieldValidator { - (value: any, values: V): any | Promise; -} - -interface FieldRef { - ( - validateOrOptions: - | FieldValidator - | { - validate?: FieldValidator; - valueAsNumber?: boolean; - valueAsDate?: boolean; - parse?: Parse; - } - ): ( - field: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null - ) => void; -} - -interface GetState { - ( - path: string | string[] | Record, - options?: { - target?: string; - watch?: boolean; - filterUntouchedErrors?: boolean; - } - ): any; -} - -interface SetErrors { - ( - errors?: Errors | ((previousErrors: Errors) => Errors | undefined) - ): void; -} - -interface SetFieldError { - (name: string, error?: any | ((previousError?: any) => any)): void; -} - -type ValuesArg = V | ((previousValues: V) => V); - -interface SetValues { - ( - values: ValuesArg, - options?: { - shouldValidate?: boolean; - touchedFields?: string[]; - dirtyFields?: string[]; - } - ): void; -} - -interface SetFieldValue { - ( - name: string, - value: any | ((previousValue: any) => any), - options?: { - [k in "shouldValidate" | "shouldTouched" | "shouldDirty"]?: boolean; - } - ): void; -} - -interface ValidateForm { - (): Promise>; -} - -interface ValidateField { - (name: string): Promise>; -} - -interface Reset { - ( - values?: ValuesArg | null, - exclude?: (keyof FormState)[] | null, - event?: SyntheticEvent - ): void; -} - -interface Submit { - (event?: SyntheticEvent): Promise<{ values?: V; errors?: Errors }>; -} - -interface Parse { - (value: V): R; -} - -type Format = Parse; - -interface OnChange { - (event: E, value?: any): void; -} - -interface OnBlur { - (event: FocusEvent): void; -} - -interface Controller { - ( - name: string, - options?: { - validate?: FieldValidator; - value?: any; - defaultValue?: any; - parse?: Parse; - format?: Format; - onChange?: OnChange; - onBlur?: OnBlur; - } - ): { - name: string; - value: any; - onChange: (event: E) => void; - onBlur: OnBlur; - } | void; -} - -interface Config { - defaultValues: V; - validate?: FormValidator; - validateOnChange?: boolean; - validateOnBlur?: boolean; - ignoreFields?: string[]; - onReset?: OnReset; - onSubmit?: OnSubmit; - onError?: OnError; - debug?: Debug; -} - -interface Return { - form: RefObject; - field: FieldRef; - getState: GetState; - setErrors: SetErrors; - setFieldError: SetFieldError; - setValues: SetValues; - setFieldValue: SetFieldValue; - validateForm: ValidateForm; - validateField: ValidateField; - reset: Reset; - submit: Submit; - controller: Controller; -} - -const useForm: ( - config: Config -) => Return; - -const get: (object: any, path: string, defaultValue?: unknown) => any; - -const set: ( - object: any, - path: string, - value: unknown, - immutable?: boolean -) => any; - -const unset: (object: any, path: string, immutable?: boolean) => any; -``` +✨ Pretty easy right? `react-cool-form` is more powerful than you think. Let's [explore it](https://react-cool-form.netlify.app)! ## Milestone