Skip to content

Commit d78ccc1

Browse files
bocembocembocembocem
authored
docs: add docs (#18)
1 parent 35b25b3 commit d78ccc1

File tree

4 files changed

+329
-5
lines changed

4 files changed

+329
-5
lines changed

‎README.md‎

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# @gravity-ui/dynamic-forms · [![npm package](https://img.shields.io/npm/v/@gravity-ui/dynamic-forms)](https://www.npmjs.com/package/@gravity-ui/dynamic-forms) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/dynamic-forms/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/dynamic-forms/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/dynamic-forms/)
22

3-
This is a template for typical package.
4-
5-
1. Create a new repository and use this repository as a template.
6-
2. Replace `dynamic-forms` through the whole repository with your name.
7-
3. Overwrite other things at your desire.
3+
The JSON Schema-based library for rendering forms and form values.
84

95
## Install
106

@@ -13,3 +9,36 @@ npm install --save-dev @gravity-ui/dynamic-forms
139
```
1410

1511
## Usage
12+
13+
```jsx
14+
import {DynamicField, Spec, dynamicConfig} from '@gravity-ui/dynamic-forms';
15+
16+
// To embed in a final-form
17+
<DynamicField name={name} spec={spec} config={config} />;
18+
19+
import {DynamicView, dynamicViewConfig} from '@gravity-ui/dynamic-forms';
20+
21+
// To get an overview of the values
22+
<DynamicView value={value} spec={spec} config={dynamicViewConfig} />;
23+
```
24+
25+
### I18N
26+
27+
Certain components include text tokens (words and phrases) that are available in two languages: `en` (the default) and `ru`. To set the language, use the `configure` function:
28+
29+
```js
30+
// index.js
31+
32+
import {configure, Lang} from '@gravity-ui/dynamic-forms';
33+
34+
configure({lang: Lang.Ru});
35+
```
36+
37+
## Development
38+
39+
To start the development server with storybook execute the following command:
40+
41+
```shell
42+
npm ci
43+
npm run dev
44+
```

‎docs/config.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
## Config
2+
3+
`Config` is an object that contains [Inputs](#inputs), [Layouts](#layouts), and [Validators](#validators) for each entity. You can modify, replace, or write your own configuration file.
4+
5+
[Default config](../src/lib/kit/constants/config.tsx)
6+
7+
### Inputs
8+
9+
`Inputs` are components, such as text fields, selectors, checkboxes, and so on, that allow users to interact with the form. `Inputs` are classified into two types: simple and independent. A `simple` `Input` [Controller](./lib.md#controller) wraps in [Layout](#layouts), while an `independent` `Input` [Controller](./lib.md#controller) is passed [Layout](#layouts) into a prop, allowing the component to wrap itself.
10+
11+
```typescript
12+
type InputEntity = {
13+
Component: React.ComponentType<
14+
{
15+
spec: Spec;
16+
name: string;
17+
} & FieldRenderProps
18+
>;
19+
independent?: false;
20+
};
21+
```
22+
23+
```typescript
24+
type IndependentInputEntity = {
25+
Component: React.ComponentType<
26+
{
27+
spec: Spec;
28+
name: string;
29+
Layout: LayoutType | undefined;
30+
} & FieldRenderProps
31+
>;
32+
independent: true;
33+
};
34+
```
35+
36+
### Layouts
37+
38+
`Layouts` are components, such as sections, cards, and accordions, that wrap the [Input](#inputs). `Layouts` receive the same props as inputs, excluding the `Layout`.
39+
40+
```typescript
41+
type LayoutType = React.ComponentType<
42+
{
43+
spec: Spec;
44+
name: string;
45+
} & FieldRenderProps
46+
>;
47+
```
48+
49+
### Validators
50+
51+
`Validators` are functions that validate field values using [spec](./spec.md#specs). If the `validator` parameter is not specified in the [spec](./spec.md#specs), the default value from the [config](#config) is used.
52+
53+
```typescript
54+
(spec: Spec, value?: Value) => string | boolean | undefined | Promise<string | boolean | undefined>;
55+
```
56+
57+
## ViewConfig
58+
59+
`ViewConfig` is an object that contains the [Views](#views) and [ViewLayouts](#viewlayouts) associated with each entity. You can modify, replace, or write your own configuration file.
60+
61+
[Default config](../src/lib/kit/constants/config.tsx)
62+
63+
### Views
64+
65+
`Views` are the components responsible for rendering the entity value. There can be two types of views: simple and independent. A `simple` `View` [ViewController](./lib.md#viewcontroller) wraps in [ViewLayout](#viewlayouts), whereas an `independent` `View` [ViewController](./lib.md#viewcontroller) is passed [ViewLayout](#viewlayouts) into the props, allowing the component to wrap itself.
66+
67+
```typescript
68+
type ViewEntity = {
69+
Component: React.ComponentType<{
70+
spec: Spec;
71+
name: string;
72+
value?: FormValue;
73+
linkValue?: React.ReactElement;
74+
}>;
75+
independent?: false;
76+
};
77+
```
78+
79+
```typescript
80+
type IndependentViewEntity = {
81+
Component: React.ComponentType<{
82+
spec: Spec;
83+
name: string;
84+
value?: FormValue;
85+
linkValue?: React.ReactElement;
86+
Layout: ViewLayoutType | undefined;
87+
}>;
88+
independent: true;
89+
};
90+
```
91+
92+
### ViewLayouts
93+
94+
`ViewLayouts` are the components, such as sections, cards, accordions, and so on, that wrap [View](#views). The `ViewLayout` receives the same props as in [View](#views), excluding `linkValue` and the `ViewLayout`.
95+
96+
```typescript
97+
type ViewLayoutType = React.ComponentType<{
98+
spec: Spec;
99+
name: string;
100+
value?: FormValue;
101+
}>;
102+
```

‎docs/lib.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Dynamic forms
2+
3+
The library uses [specs](./spec.md#specs) to describe the entities of arrays, objects, strings, numbers, and boolean values. The entity description includes instructions for drawing and validating the entity. The library interacts on two levels: [Layouts](./config.md#layouts) and [Inputs](./config.md#inputs).
4+
5+
And it is intended to be used with `final-form`.
6+
7+
## Form
8+
9+
### DynamicField
10+
11+
This component serves as the primary entry point for drawing dynamic forms.
12+
13+
| Property | Type | Required | Description |
14+
| :------- | :--------------------------------------- | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| name | `string` | yes | Field name |
16+
| spec | `Spec` | yes | A [spec](./spec.md#specs) describing the entity |
17+
| config | `DynamicFormConfig` | yes | A [config](./config.md) containing [Inputs](./config.md#inputs), [Layouts](./config.md#layouts), and [validators](./config.md#validators) for each entity |
18+
| Monaco | `React.ComponentType<MonacoEditorProps>` | | [MonacoEditor](https://github.com/react-monaco-editor/react-monaco-editor) component for Monaco [Input](./config.md#inputs) |
19+
| search | `string \| function` | | A string or function for performing a form search |
20+
21+
### Controller
22+
23+
This component locates all required rendering elements and renders the entity.
24+
25+
| Property | Type | Required | Description |
26+
| :-------------- | :---------------------------------------------------------------------------------------------------------- | :------: | :----------------------------------------------- |
27+
| name | `string` | yes | Field name |
28+
| spec | `Spec` | yes | An [spec](./spec.md#specs) describing the entity |
29+
| initialValue | `FieldValue` | yes | Initial value |
30+
| parentOnChange | `((childName: string, childValue: FieldValue, childErrors: Record<string, ValidateError>) => void) \| null` | yes | Callback for updating the parent entity's state |
31+
| parentOnUnmount | `((childName: string) => void) \| null` | yes | Callback for unmount |
32+
33+
## View
34+
35+
### DynamicView
36+
37+
This component serves as the primary entry point for creating an overview of form values.
38+
39+
| Property | Type | Required | Description |
40+
| :------- | :------------------------------------------------------------------------- | :------: | :-------------------------------------------------------------------------------------------------------------------------- |
41+
| value | `AnyObject` | yes | Form value |
42+
| spec | `Spec` | yes | An [spec](./spec.md#specs) describing the entity |
43+
| config | `DynamicViewConfig` | yes | A [config](./config.md) containing [Views](./config.md#views) and [ViewLayouts](./config.md#viewlayouts) for each entity |
44+
| Link | `React.ComponentType<{value: FormValue; link: Spec['viewSpec']['link'];}>` | | [Component](./spec.md#link) for converting values to links |
45+
| Monaco | `React.ComponentType<MonacoEditorProps>` | | [MonacoEditor](https://github.com/react-monaco-editor/react-monaco-editor) component for Monaco [Input](./config.md#inputs) |
46+
47+
### ViewController
48+
49+
This component searches for all required rendering elements and renders the entity.
50+
51+
| Property | Type | Required | Description |
52+
| :------- | :------- | :------: | :----------------------------------------------- |
53+
| name | `string` | yes | View name |
54+
| spec | `Spec` | yes | An [spec](./spec.md#specs) describing the entity |

0 commit comments

Comments
 (0)