|
1 | | -# \<widget-form> |
| 1 | +# widget-form |
2 | 2 |
|
3 | | -This webcomponent follows the [open-wc](https://github.com/open-wc/open-wc) recommendation. |
| 3 | +A Lit 3.x web component for creating dynamic forms with configurable fields. Part of the IronFlock widget ecosystem. |
| 4 | + |
| 5 | + |
4 | 6 |
|
5 | 7 | ## Installation |
6 | 8 |
|
7 | 9 | ```bash |
8 | | -npm i widget-form |
| 10 | +npm i @record-evolution/widget-form |
9 | 11 | ``` |
10 | 12 |
|
11 | 13 | ## Usage |
12 | 14 |
|
13 | 15 | ```html |
14 | 16 | <script type="module"> |
15 | | - import 'widget-form/widget-form.js' |
| 17 | + import '@record-evolution/widget-form' |
16 | 18 | </script> |
17 | 19 |
|
18 | | -<widget-form></widget-form> |
| 20 | +<widget-form-1.0.9></widget-form-1.0.9> |
19 | 21 | ``` |
20 | 22 |
|
21 | | -## Expected data format |
22 | | - |
23 | | -The following format represents the available data : |
24 | | - |
25 | | -```js |
26 | | -data: { |
27 | | - settings: { |
28 | | - title: string, |
29 | | - subTitle: string, |
30 | | - minGauge: number, |
31 | | - maxGauge: number, |
32 | | - style: { |
33 | | - needleColor: string, |
34 | | - sections: number, |
35 | | - backgroundColor: string[] |
36 | | - } |
37 | | - } |
38 | | - gaugeValue: Number |
39 | | -} |
40 | | -``` |
| 23 | +> **Note:** The version number is part of the custom element tag name. |
41 | 24 |
|
42 | | -## Interfaces |
| 25 | +## Properties |
43 | 26 |
|
44 | | -```ts |
45 | | -interface InputData { |
46 | | - settings: Settings |
47 | | - gaugeValue: number |
48 | | -} |
49 | | -``` |
| 27 | +| Property | Type | Description | |
| 28 | +| ----------- | ----------- | ----------------------------- | |
| 29 | +| `inputData` | `InputData` | Form configuration and fields | |
| 30 | +| `theme` | `Theme` | Theme object for styling | |
50 | 31 |
|
51 | | -```ts |
52 | | -interface Settings { |
53 | | - title: string |
54 | | - subTitle: string |
55 | | - minGauge: number |
56 | | - maxGauge: number |
57 | | - style: Style |
58 | | -} |
59 | | -``` |
| 32 | +## Events |
60 | 33 |
|
61 | | -```ts |
62 | | -interface Style { |
63 | | - needleColor: string |
64 | | - sections: number |
65 | | - backgroundColor: string[] |
66 | | -} |
67 | | -``` |
| 34 | +| Event | Detail | Description | |
| 35 | +| ------------- | ----------------------------- | -------------------------------- | |
| 36 | +| `data-submit` | Array of field/value mappings | Fired when the form is submitted | |
68 | 37 |
|
69 | | -## Style options |
| 38 | +## Configuration |
70 | 39 |
|
71 | | -The following options are available for styling the value graph. |
72 | | -The `sections` option splits the value area into by default three same sized sections. Therefore three different colors can be provided to the `backgroundColor` by default. |
| 40 | +The form is configured via the `inputData` property: |
73 | 41 |
|
74 | | -``` |
75 | | - interface Style { |
76 | | - needleColor: string, |
77 | | - sections: number, |
78 | | - backgroundColor: string[] |
79 | | - } |
| 42 | +```ts |
| 43 | +interface InputData { |
| 44 | + title?: string |
| 45 | + subTitle?: string |
| 46 | + formButton?: boolean // Show button to open form dialog |
| 47 | + formFields?: FormField[] |
| 48 | +} |
80 | 49 | ``` |
81 | 50 |
|
82 | | -## Linting and formatting |
| 51 | +### Field Types |
83 | 52 |
|
84 | | -To scan the project for linting and formatting errors, run |
| 53 | +Each form field supports the following types: |
85 | 54 |
|
86 | | -```bash |
87 | | -npm run lint |
88 | | -``` |
| 55 | +| Type | Description | |
| 56 | +| ------------- | ------------------------------ | |
| 57 | +| `textfield` | Single-line text input | |
| 58 | +| `numberfield` | Numeric input with min/max | |
| 59 | +| `checkbox` | Boolean checkbox | |
| 60 | +| `textarea` | Multi-line text input | |
| 61 | +| `dropdown` | Select from predefined options | |
| 62 | +| `datetime` | Date/time picker | |
89 | 63 |
|
90 | | -To automatically fix linting and formatting errors, run |
| 64 | +### Field Configuration |
91 | 65 |
|
92 | | -```bash |
93 | | -npm run format |
| 66 | +```ts |
| 67 | +interface FormField { |
| 68 | + label: string |
| 69 | + type: 'dropdown' | 'textfield' | 'numberfield' | 'checkbox' | 'textarea' | 'datetime' |
| 70 | + hiddenField?: boolean // Hide field but still submit value |
| 71 | + required?: boolean // Field must be filled |
| 72 | + description?: string // Hint text shown below field |
| 73 | + targetColumn?: TargetColumn // Database column mapping |
| 74 | + defaultValue?: string |
| 75 | + min?: number // For numberfield |
| 76 | + max?: number // For numberfield |
| 77 | + validation?: string // Regex for textfield |
| 78 | + values?: DropdownValue[] // For dropdown type |
| 79 | +} |
94 | 80 | ``` |
95 | 81 |
|
96 | | -## Tooling configs |
| 82 | +## Development |
97 | 83 |
|
98 | | -For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project. |
| 84 | +```bash |
| 85 | +# Start dev server |
| 86 | +npm run start |
99 | 87 |
|
100 | | -If you customize the configuration a lot, you can consider moving them to individual files. |
| 88 | +# Build for production |
| 89 | +npm run build |
101 | 90 |
|
102 | | -## Local Demo with `web-dev-server` |
| 91 | +# Generate types from schema |
| 92 | +npm run types |
103 | 93 |
|
104 | | -```bash |
105 | | -npm start |
| 94 | +# Build, bump version, and publish |
| 95 | +npm run release |
106 | 96 | ``` |
107 | 97 |
|
108 | | -To run a local development server that serves the basic demo located in `demo/index.html` |
| 98 | +## License |
| 99 | + |
| 100 | +MIT |
0 commit comments