-
Notifications
You must be signed in to change notification settings - Fork 55
UIForm V3
Today, @talend/ui repository has a form package. It proposes 1 api, based on json schema format. This has been done to fill tcomp/tacokit, to let the backend services control the forms with json format based document.
Json is really limited and static, and this introduces limitations in the features. To overcome some of them, and to comply in tcomp/takokit lifecycle, we introduced triggers, to have an external entry to do custom actions (change of schema, dynamic/async validation, change of suggestions, …). But the implementation is really hard to maintain and synchronize. For example validation has 3 entry points:
- (backend) Json Schema: static validation on single elements
- (frontend) Component custom validation props: complex single element validation
- (frontend/backend) Trigger: static/async validation on global/single element(s)
The result is that
- Frontend developers struggle to create frontend-only forms, writing tons of json instead of components, without being able to fulfill complex cases
- Backend developers struggle too, trying to implement complex validations with json and UIForm limited features.
We need to open this implementation, to let frontend developers write their custom/complex use cases, and have a validation format flexible enough, that we can convert to the open implementation.
(TODO)
@talend/react-forms has a custom implementation. The json schema is present at every level of the implementation, from top level form to widget internal code. It’s very hard to extract the schema part to a top level to allow developers to use the widgets as components. A better and less costly solution would be to base the implementation on an existing library. The developers would be able to use the library (or the wrapper on it), and backend users would still be able to use our custom schema layer on top of it.
Github stars | Maintained | Contributors | Issues | |
---|---|---|---|---|
Formik | 19.1k | By @jaredpalmer | 268 | 376 |
React-hook-forms | 4.2k | By @bluebill1049 | 38 | 1 |
Weekly dl | Size | Dependencies | |
---|---|---|---|
Formik | 307k | 12.6kB | 9 |
React-hook-forms | 30k | 5.2kB | 0 |
Formik was created by @jaredpalmer who is very active in the frontend community. The library is very popular and well maintained. It has tons of contributors and more than 19k stars.
React-hook-form is quite young, it was created in march 2019 by @bluebill1049, but has risen quite fast, having now more than 4k stars. It is a very light library, with no dependencies. It has a documentation for advanced cases such as custom widget, accessibility, or wizard.
The goal is to compare the developer experience and the possibilities between the 2 libraries and our current implementation. We will focus on the component part, as we don’t want to break the api for schema part.
Basis
Scenario | Story |
---|---|
B1 | as a developer, I want to create a simple form with email and password, with submit function |
B2 | as a developer, I want to add a custom widget |
Validation
Scenario | Story |
---|---|
V1 | as a developer, I want to validate the email pattern and password requirement |
V2 | as a developer, I want to async validate the email, checking it’s availability |
V3 | as a developer, I want to do a complex validation, with values dependencies |
Advanced
Scenario | Story |
---|---|
A1 | as a developer, I want to set a field required depending on another value |
A2 | as a developer, I want to show/hide a new field depending on another value |
{
"jsonSchema": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"email": {
"type": "string"
}
}
},
"password": { "type": "string" }
}
},
"uiSchema": [
{
"key": "user.email",
"title": "Email"
},
{
"key": "password",
"title": "Password"
}
],
"properties": {
"user": {
"email": "[email protected]"
}
}
}
import { UIForm } from "@talend/react-forms/lib/UIForm";
import data from "./schema.json";
function ExampleForm() {
const onSubmit = (event, data) => {
console.log(data);
};
return <UIForm data={data} onSubmit={onSubmit} />;
}
On a simple form, it stays simple. You have 3 parts:
- json schema: defines the model
- ui schema: defines the widgets
- properties: defines the default values
import React from "react";
import { Formik, Form, Field } from "formik";
function ExampleForm() {
const onSubmit = data => {
console.log(data);
};
return (
<Formik
initialValues={{ user: { email: "[email protected]" } }}
onSubmit={onSubmit}
>
{args => {
const { isSubmitting } = args;
return (
<Form>
<div className="form-group">
<label htmlFor="email">Email</label>
<Field id="email" type="email" name="user.email" />
</div>
<div className="form-group">
<label htmlFor="email">Password</label>
<Field id="password" type="password" name="password" />
</div>
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</Form>
);
}}
</Formik>
);
}
Formik offers to write javascript instead of json. Each form and field components come from the library.
Compared to the schema
- the structure is tied to the field names
- the default values are passed at Formik component level
There are some extra features to manage some status. In the example above, the isSubmitting
flag allows to avoid submitting twice the form.
import React from "react";
import useForm from "react-hook-form";
function App() {
const { register, handleSubmit } = useForm();
const onSubmit = data => {
console.log(data);
};
return (
<form onSubmit={onSubmit} noValidate>
<div className="form-group">
<label htmlFor="email">Email</label>
<input
id="email"
type="email"
name="user.email"
defaultValue="[email protected]"
ref={register}
/>
</div>
<div className="form-group">
<label htmlFor="email">Password</label>
<input id="password" type="password" name="password" ref={register} />
</div>
<button type="submit">Submit</button>
</form>
);
}
export default App;
React-hook-form uses native elements (form, input, ...), allowing to write classical html/jsx, but wiring elements to the form system via ref and functions from the hook.
Lib | Summary | Jimmy's opinion | Jean Michel's opinion | Eligible |
---|---|---|---|---|
UIForm | Almost no js code, simple json description. | ✅ | ||
Formik | Components from the lib. | ✅ | ||
React-hook-form | Native elements to wire with hook. | ✅This is clearly an advantage to stay with native elements | ✅ |
{
"jsonSchema": {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"email": {
"type": "string"
}
}
},
"password": { "type": "string" },
+ "extraField": {
+ "type": "object",
+ "properties": {
+ "key": {
+ "type": "string"
+ },
+ "value": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
"uiSchema": [
{
"key": "user.email",
"title": "Email"
},
{
"key": "password",
"title": "Password"
},
+ {
+ "key": "extraField",
+ "title": "Extra field",
+ "items": [
+ {
+ "key": "extraField.key",
+ "title": "Key"
+ },
+ {
+ "key": "extraField.value",
+ "title": "Private value",
+ "type": "password"
+ }
+ ],
+ "widget": "keyValue"
+ }
],
"properties": {
"user": {
"email": "[email protected]"
}
}
}
import { UIForm } from '@talend/react-forms/lib/UIForm';
import data from './schema.json';
+import KeyValue from './KeyValue.component';
function ExampleForm() {
const onSubmit = (event, data) => {
console.log(data);
};
+ const widgets = {
+ keyValue: KeyValue,
+ };
return (
<UIForm
data={data}
onSubmit={onSubmit}
+ widgets={widgets}
/>
);
}
UIForm comes with a set of widgets, loaded by default. This allows to not pass the widgets everytime, but makes the bundle heavier even if you don't use them.
The widget configuration is still in the json schema. We have to know describe the widget value format, and describe the widget inputs, sometimes having heavy nestings in term of level and quantity.
import { Field } from "formik";
function KeyValue({ field }, id, label, keyProps, valueProps) {
const { name } = field;
const { label: keyLabel, ...restKeyProps } = keyProps;
const { label: valueLabel, ...restValueProps } = valueProps;
const keyName = `${name}.key`;
const valueName = `${name}.value`;
const keyId = `${id}.key`;
const valueId = `${id}.value`;
return (
<fieldset>
<legend>{label}</legend>
<div className="form-group">
<label htmlFor={keyId}>{keyLabel}</label>
<Field id={keyId} type="text" name={keyName} {...restKeyProps} />
</div>
<div className="form-group">
<label htmlFor="email">{valueLabel}</label>
<Field
id={valueId}
type="text"
name={`${name}.key`}
{...restValueProps}
/>
</div>
</fieldset>
);
}
The widget use the same Field
component from Formik for its inputs.
import React from 'react';
import { Formik, Form, Field } from 'formik';
import KeyValue from './KeyValue.component';
function ExampleForm() {
const onSubmit = data => {
console.log(data);
};
return (
<Formik
initialValues={{ user: { email: "[email protected]" } }}
onSubmit={onSubmit}
>
{args => {
const { isSubmitting } = args;
return (
<Form>
<div className="form-group">
<label htmlFor="email">Email</label>
<Field id="email" type="email" name="user.email" />
</div>
<div className="form-group">
<label htmlFor="email">Password</label>
<Field id="password" type="password" name="password" />
</div>
<div className="form-group">
<label htmlFor="email">Extra field</label>
<Field id="password" type="password" name="password" />
</div>
+ <Field
+ id="extra-field"
+ name="keyValue"
+ component={KeyValue}
+ label="Extra field"
+ keyProps={{ label: 'Key' }}
+ valueProps={{ label: 'Private value', type: 'password' }}
+ />
<button type="submit" disabled={isSubmitting}>
Submit
</button>
</Form>
);
}}
</Formik>
);
}
We use the Field
component, passing the component to render as component
props and name that the widget will manage. The rest of props are just passed to the widget.
import { useEffect } from "react";
function KeyValue({
id,
label,
name,
keyProps,
valueProps,
register,
unregister
}) {
const { label: keyLabel, ...restKeyProps } = keyProps;
const { label: valueLabel, ...restValueProps } = valueProps;
const keyId = `${id}.key`;
const valueId = `${id}.value`;
const keyName = `${name}.key`;
const valueName = `${name}.value`;
useEffect(() => {
return () => {
unregister(keyName);
unregister(valueName);
}, []);
return (
<fieldset>
<legend>{label}</legend>
<div className="form-group">
<label htmlFor={keyId}>{keyLabel}</label>
<input id={keyId} type="text" name={keyName} ref={register} {...restKeyProps} />
</div>
<div className="form-group">
<label htmlFor="email">{valueLabel}</label>
<input
id={valueId}
type="text"
name={valueName}
ref={register}
{...restValueProps}
/>
</div>
</fieldset>
);
}
In the widget, we use native elements again, passing react-hook-form register()
function. But we have to unregister them at widget unmount.
import React from "react";
import useForm from "react-hook-form";
+import KeyValue from "./KeyValue.component";
function App() {
- const { register, handleSubmit } = useForm();
+ const { register, unregister, handleSubmit } = useForm();
const onSubmit = data => {
console.log(data);
};
return (
<form onSubmit={onSubmit} noValidate>
<div className="form-group">
<label htmlFor="email">Email</label>
<input
id="email"
type="email"
name="user.email"
defaultValue="[email protected]"
ref={register}
/>
</div>
<div className="form-group">
<label htmlFor="email">Password</label>
<input id="password" type="password" name="password" ref={register} />
</div>
+ <KeyValue
+ id="extra-field"
+ name="keyValue"
+ label="Extra field"
+ keyProps={{ label: 'Key' }}
+ valueProps={{ label: 'Private value', type: 'password' }}
+ register={register}
+ unregister={unregister}
+ />
<button type="submit">Submit</button>
</form>
);
}
export default App;
In the form, we use the component directly in jsx, passing the register/unregister
functions.
Lib | Summary | Jimmy's opinion | Jean Michel's opinion | Eligible |
---|---|---|---|---|
UIForm | Pass widgets to the form to registry, it comes with a set of widgets which is good in term of usability, but bad in term of bundle size. | This solution is still needed for backend control via json | ✅ | |
Formik | Import widget and use it as Field . |
✅ More control to the dev and able to tree shake | ✅ | |
React-hook-form | Import widget and use it as jsx component. But need to manage unregister. | ✅ More control to the dev and able to tree shake | ✅ |
UIForms | Formik | React-hook-form | |
---|---|---|---|
Simple forms | ✅ | ✅ | ✅ |
Custom widget | ❌ for FE only, ✅ for backend control | ✅ | ✅ |
❌ | ❌ | ❌ |