Merge pull request #823 from rvsia/updateDocs

Update docs, make them more interesting and searchable

Author: Hyperkid123

packages/react-renderer-demo/src/components/landing-page/landing-page-cards.js

@@ -319,7 +319,11 @@ const LandingPageCards = () => {
               <Typography variant="body2" gutterBottom className={classes.mappersText}>
                 This list represents a set of provided mappers. Each mapper brings all basic form components from its design system. You can
                 immediately use form inputs such as text fields, selects, radios, checkboxes or wizards. However, this selection does not limit you as
-                integrating custom components is simple as it can be - all it takes is just one hook.
+                integrating custom components is simple as it can be - all it takes is just{' '}
+                <RouterLink href="/mappers/carbon-component-mapper">
+                  <a href="/mappers/carbon-component-mapper">one hook</a>
+                </RouterLink>
+                .
               </Typography>
             </Grid>
           </Grid>

packages/react-renderer-demo/src/pages/hooks/use-form-api.md

@@ -20,18 +20,58 @@ const Component = (props) => {
 
 This hook returns object containing following information:
 
-```jsx
-{
-  blur: (name) => void, // calls onBlur event on field with given name
-  change: (name, value) => void, // calls onChange event on field with given name
-  focus: (name) => void, // calls onFocus event on field with given name
-  getFieldState: (name) => object, // returns a state of given field, state contains input and meta information of field
-  getRegisteredFields: () => string[], // returns an array of field names that are rendered in DOM
-  getState: () => object, // returns an object with whole form state. More info https://final-form.org/docs/final-form/types/FormState
-  pristine: bool, // true if the all field values is === to the initial values, false if the values are !==.
-  renderForm: (defaultSchema) => void, // function that is used by form renderer to render form fields defined by defaultSchema; can be used for schema nesting
-  valid: bool //true if all fields have no validation or submission errors. false otherwise.
-}
-```
+## renderForm
+
+*(fields: schema) => React.Element*
+
+If you want to render fields from a component (`tabs`, `subform`, etc.) you can use `renderForm(fields)` function.
+
+## getState
+
+*() => FormState*
+
+Using `getState` components you get an access to [the form state](https://final-form.org/docs/final-form/types/FormState). Be aware of subscription - if your component is not subscribed to the form state, it won't be updated when the state is changed. See [FormSpy](/components/form-spy).
+
+## change
+
+*(name: string, value: any) => void*
+
+You can change value of any field using this function.
+
+## focus
+
+*(name: string) => void*
+
+Calls onFocus event on field with given name.
+
+## blur
+
+*(name: string) => void*
+
+Calls onBlur event on field with given name.
+
+## getFieldState
+
+*(name: string) => FormFieldState*
+
+Returns a state of given field. State contains input and meta information of the field.
+
+## getRegisteredFields
+
+*() => string[]*
+
+Returns an array of field names that are currently rendered in DOM. Useful to know when you collect variables in wizard forms.
+
+## pristine
+
+*boolean*
+
+True if the all field values is === to the initial values, false if the values are !==. Same as in the FormState.
+
+## valid
+
+*boolean*
+
+True if all fields have no validation or submission errors. false otherwise. Same as in the FormState.
 
 </DocPage>

packages/react-renderer-demo/src/pages/installation.md

@@ -16,13 +16,15 @@ yarn add @data-driven-forms/react-form-renderer
 
 ## Mappers
 
-Data Driven Forms team provides and mantains basic set of components for following design systems:
+Data Driven Forms team provides and mantains basic set of components for following design systems. You can use them to build forms without ingerating your own components.
 
 - [MaterialUI](/mappers/mui-component-mapper)
 - [Semantic UI](/mappers/suir-component-mapper)
 - [BlueprintJS](/mappers/blueprint-component-mapper)
 - [PatternFly 4](/mappers/pf4-component-mapper)
 - [PatternFly 3](/mappers/pf3-component-mapper)
+- [Ant Design](/mappers/ant-component-mapper)
+- [Carbon Design](/mappers/carbon-component-mapper)
 
 ## Versioning
 

packages/react-renderer-demo/src/pages/introduction.md

@@ -5,21 +5,30 @@ import CodeExample from '@docs/code-example';
 
 # Data Driven Forms Introduction
 
-Data Driven Forms converts JSON form definitions into fully functional React forms.
-It uses [React Final Form](https://github.com/final-form/react-final-form) for the form state management.
-It is highly recommended to check their documentations first to fully understand how
-the [Data Driven Forms](https://github.com/data-driven-forms/react-forms) libraries work.
+Data Driven Forms converts JSON form definitions (schemas) into fully functional React forms with the provided set of features.
 
-All you need is to [install](/installation) the form renderer and choose the component mapper you want ([or create your own](/mappers/custom-mapper)).
+## Form state management
 
-Import `FormRenderer` from the react-form-renderer. This component takes four required props: FormTemplate, schema, componentMapper and onSubmit. You can read about them [here](/components/renderer#requiredprops).
+Data Driven Forms uses [React Final Form](https://github.com/final-form/react-final-form) for the form state management. It is recommended to check their documentations first to fully understand how the [Data Driven Forms](https://github.com/data-driven-forms/react-forms) libraries work. However, it's not required to use DDF library.
 
-You can check the simple example below.
+## Schema
+
+[A schema](/schema/introduction) is a JSON object controlling the whole form. Using schema you define form fields and its attributes.
+
+## How to start
+
+All you need is to [install](/installation) the form renderer and then to choose components you want to use. You can use one of provided mappers to start building forms right away ([or integrate your own components](/mappers/custom-mapper)). The integration is simple - all it takes is just a single [useFieldApi](/hooks/use-field-api) hook.
+
+Then you can import `FormRenderer` from the `@data-driven-forms/react-form-renderer`. This component takes four required props: **FormTemplate**, **schema**, **componentMapper** and **onSubmit**. You can read about them [here](/components/renderer#requiredprops).
+
+Following example shows basic usage of Data Driven Forms library with our [Material UI mapper](/mappers/mui-component-mapper).
 
 <CodeExample source="components/get-started/get-started" mode="preview" />
 
 ## Articles
 
+Following articles can give you more insights about Data Driven Forms and why/how to use it in you projects.
+
 ### Introduction of data driven approach
 
 [This article](https://medium.com/javascript-in-plain-english/data-driven-approach-to-forms-with-react-c69fd4ea7923) presents basics of the data driven approach and why to choose it.
@@ -28,4 +37,18 @@ You can check the simple example below.
 
 [This article](https://medium.com/javascript-in-plain-english/data-driven-form-building-in-react-30768b49e625) presents basics of the data driven form building. It is a great point to start if you are new with this library.
 
+## Comparison with other form libraries
+
+### Form state management
+
+You can find many of already existing and well-established libraries such as Formik, React Hook Form, or React Final Form. These libraries are focused on providing form state management solutions. Data Driven Forms is using one of them - React Final Form - to enhance the developer experience and to provide consistent way for building complex forms. Form state management is completely abstracted in Data Driven Forms, so developers can focus on the only thing that really matters - building the most accessible web forms.
+
+### Data driven libraries
+
+Also, there are multiple libraries generating forms from schemas (i.e. Uniforms, AntD Form component). Mostly these libraries are using one of well-known formats such as JSON Schemas or GraphQL schemas. Data Driven Forms implements its own format to provide the most simple representation of forms - it's not being used to define data, it's directly designed to define forms so it's simple, logical and it allows to use many of form-specific features.
+
+Data Driven Forms provides complex conditional logic to hide your fields, fully dynamic wizard forms, and much more. Also, its API allows to store complex forms in databases, so you can reuse forms in multiple developer environments.
+
+If users need to use generate forms from GraphQL, all that is needed is to convert the GraphQL schema to DDF one.
+
 </DocPage>

packages/react-renderer-demo/src/pages/mappers/custom-mapper.md

@@ -60,6 +60,30 @@ Data Driven Forms will render any component you pass to it, so you don't have to
 const Title = ({component, name, label, ...props }) => <h1 id={name} {...props}>{label}</h1>
 ```
 
+### Form methods
+
+Using [useFormApi](/hooks/use-form-api) you can get access to mutliple form methods without connecting a form field. Some most used methods are following:
+
+**renderForm**
+
+*(fields) => React.Element*
+
+If you want to render fields from a component (`tabs`, `subform`, etc.) you can use `renderForm(fields)` function.
+
+**getState**
+
+*() => FormState*
+
+Using `getState` components you get an access to the form state. Be aware of subscription - if your component is not subscribed to the form state, it won't be updated when the state is changed. See [FormSpy](/components/form-spy).
+
+**change**
+
+*(name, value) => void*
+
+You can change value of any field using this function.
+
+---
+
 ## Register component in component mapper
 
 To be able to use your component in the schema, you need to register the component in your component mapper.

packages/react-renderer-demo/src/pages/migration-guide.md

@@ -35,7 +35,9 @@ Thank you for your understanding.
     -   disableSubmit
     -   buttonClassName
     -   renderFormButtons
-    -   buttonsLabels
+    -   submitLabel
+    -   cancelLabel
+    -   resetLabel
     -   canReset
 -   => All these props are now managed by mapper's form templates!
 

packages/react-renderer-demo/src/pages/schema/clear-on-unmount.md

@@ -5,6 +5,8 @@ import CodeExample from '@docs/code-example';
 
 # Clear on unmount
 
+*boolean*
+
 When using dynamic forms where more fields share the same name, the value is preserved when a user switches the field. You can disable this behavior by setting 
 `clearOnUnmount` option in the renderer component or in the schema of the field. The option in the schema has always higher priority. (When 
 `clearOnUnmount` is set in the renderer and the field has it this attribute set to `false`, the field value will not be cleared.)

packages/react-renderer-demo/src/pages/schema/cleared-value.md

@@ -5,6 +5,8 @@ import DocPage from '@docs/doc-page';
 
 # Cleared value
 
+*any*
+
 The value to send upon a submit if the field is empty. This wildcard value can be used to distinguish between an untouched field and a cleared one (it will be only used when field has initialValue). For example if you have a form that edits an entity and you would like to clear an attribute. Some APIs require the value to be set to null to register the change.
 
 

packages/react-renderer-demo/src/pages/schema/data-types.md

@@ -5,9 +5,22 @@ import DocPage from '@docs/doc-page';
 
 # Data Types
 
+*string*
+
  You can specify a type of a component by providing `dataType`, which will automatically validates the component value.
 Because almost everything in HTML inputs is outputed as a string, adding the `dataType` props will also cast the value to given type.
 
+## Example
+
+```jsx
+{
+    component: 'text-field',
+    name: 'age',
+    label: 'How old are you?',
+    dataType: 'number'
+}
+```
+
 ## Available dataTypes
 
  ```jsx

packages/react-renderer-demo/src/pages/schema/initialize-on-mount.md

@@ -5,6 +5,8 @@ import CodeExample from '@docs/code-example';
 
 # Initialize On Mount
 
+*boolean*
+
 Data Driven Forms provides a way how you can easily initialized a field when the field is mounted (re-mounted).
 
 Just pass a `initializeOnMount` prop and set it to `true`.