From cc4012ad44f1c410ac1fb14eff80b6d4a1b0c15b Mon Sep 17 00:00:00 2001 From: JoseLion Date: Sat, 12 Aug 2023 00:34:45 -0500 Subject: [PATCH] docs(validations): Add Zod support and Adapter feature --- README.md | 6 ++--- packages/core/README.md | 49 ++++++++++++++++++++++++++++++++++++--- packages/native/README.md | 5 ++-- packages/web/README.md | 5 ++-- 4 files changed, 53 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 166b137..c74e825 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ TypeScript-first, lightning fast Forms for React.js and React Native. Lynx.ts is a [React Context](https://react.dev/learn/passing-data-deeply-with-context) based Form Provider. However, thanks to the brilliant [use-context-selector](https://github.com/dai-shi/use-context-selector) the re-renders caused by changes in the context are drastically reduced. The `use-context-selector` hook implements [React's RFC context selector](https://github.com/reactjs/rfcs/pull/119) in user land, this way we can specifically select what we need from the context and avoid unnecessary re-renders when unused parts of the context change. -Being a TypeScript-first library, you'll find type-safety on every turn: validation, simple/array/nested fields, form submision, etc. The codebase also follows a [full memoization principle](https://attardi.org/why-we-memo-all-the-things/), which makes Lynx.ts fast and ready for small and big projects. +Being a TypeScript-first library, you'll find type-safety on every turn: validation, simple/array/nested fields, form submision, etc. The codebase also follows a [full memoization principle](https://attardi.org/why-we-memo-all-the-things/), which makes Lynx.ts fast and performant on small or big projects. ## Compatibility @@ -34,9 +34,9 @@ Check each package documentation for more details on how to use them. ## Design and next steps -The intention is to keep this library small and simple. So initially, the validation only supports a [Yup](https://github.com/jquense/yup) schemas. However, the intention is to add support for [Zod](https://zod.dev/) moving forward and based user requests. A third option to add custom validators can be implememted if requested too. +Validation is a crutial part of forms in most cases. For Lynx.ts validation is always required, but because it can be a whole project out on its own, validation is supported through 3rd-party libraries. Both [Yup](https://github.com/jquense/yup) and [Zod](https://zod.dev/) schemas are supported out-of-the-box, but you can use any other library by just implementing an `Adapter` which tells the form how to validate the schema. Check the Core package documentation for more details on [custom validation adapters](./packages/core/README.md#validation-adapters). In the remote case you don't need to validate your forms, we provide a `noValidate()` adapter which you can use as well. -Same as with the schema, errors have a single behavior. They are present only if the **field is dirty or the form was submitted**. Adding other behaviors will be based on requests and their use cases. +Errors are present only if the **field was touched or the form submitted**. Adding other behaviors to how errors show will be based on requests and their use cases. Feel free to open an issue and share yours! ## Something's missing? diff --git a/packages/core/README.md b/packages/core/README.md index a9bc5fd..8b187e1 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -16,18 +16,17 @@ TypeScript-first, lightning fast Forms for React.js and React Native. The `@lynx ## Requirements - **[React.js](https://react.dev/):** >=16.8.0 -- **[Yup](https://github.com/jquense/yup):** >=1.0.0 ## Install Using Yarn: ``` -yarn add @lynxts/core react yup +yarn add @lynxts/core ``` Using NPM: ``` -npm i @lynxts/core react yup +npm i @lynxts/core ``` ## Usage @@ -255,6 +254,50 @@ const ArrayField = arrayFieldOf(); ``` +### Validation adapters + +Lynx.ts works out-of-the-box with both [Yup](https://github.com/jquense/yup) and [Zod](https://zod.dev/) schemas, but if you'd prefer to use a different library, you need only to implement an `Adapter` which tells Lynx.ts how the validation should work. + +```ts +interface Adapter { + required: (path: Path) => boolean; + validate: (values: Partial) => Promise, string>>>; + validateAt: (path: Path, value: V) => Promise>; +} +``` + +An `Adapter` consist on implementing three function: + +- **required:** A function that tells if a field in a path is required or not. +- **validate:** A function used to validate the Form values against a schema. +- **validateAt:** A function used to validate a single field value in a path. + +The `validation` prop accepts either a Yup/Zod schema or a custom adapter, so you could create an function that creates an adapter from your especific schema: + +```tsx + + {/* ... */} + +``` + +#### Bypass validation + + +If you wish not use any validation at all, Lynx.ts provides a `noValidate()` adapter you can use for this purpose. + +```tsx +import { FormProvider, noValidate } from "@lynxts/core"; + +interface User { + age: number; + name: string; +} + + onSubmit={handleSubmit} validation={noValidate()}> + {/* ... */} + +``` + ## Something's missing? Suggestions are always welcome! Please create an [issue](https://github.com/JoseLion/lynxts/issues/new) describing the request, feature, or bug. We'll try to look into it as soon as possible 🙂 diff --git a/packages/native/README.md b/packages/native/README.md index 76233f7..a7dbc13 100644 --- a/packages/native/README.md +++ b/packages/native/README.md @@ -18,18 +18,17 @@ TypeScript-first, lightning fast Forms for React.js and React Native. The `@lynx - **[lynxts/core](../core/README.md):** Same as the `@lynxts/native` version used - **[React.js](https://react.dev/):** >=16.8.0 - **[React Native](https://react.dev/):** >=0.59.0 -- **[Yup](https://github.com/jquense/yup):** >=1.0.0 ## Install Using Yarn: ``` -yarn add @lynxts/core @lynxts/native react react-native yup +yarn add @lynxts/core @lynxts/native ``` Using NPM: ``` -npm i @lynxts/core @lynxts/native react react-native yup +npm i @lynxts/core @lynxts/native ``` ## Usage diff --git a/packages/web/README.md b/packages/web/README.md index 0bbdc24..8829d03 100644 --- a/packages/web/README.md +++ b/packages/web/README.md @@ -13,20 +13,19 @@ TypeScript-first, lightning fast Forms for React.js and React Native. The `@lynx * [**lynxts/core**](../core/)**:** Same as the `@lynxts/web` version used * [**React.js**](https://react.dev/)**:** >=16.8.0 * [**React DOM**](https://www.npmjs.com/package/react-dom)**:** >=16.8.0 -* [**Yup**](https://github.com/jquense/yup)**:** >=1.0.0 ### Install Using Yarn: ``` -yarn add @lynxts/core @lynxts/web react react-dom yup +yarn add @lynxts/core @lynxts/web ``` Using NPM: ``` -npm i @lynxts/core @lynxts/web react react-dom yup +npm i @lynxts/core @lynxts/web ``` ### Usage