fg-dynamic-component 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,249 @@
1
+ # fg-dynamic-component
2
+
3
+ > Create a standalone signals based dynamic components tree through a JSON configuration with full life-cycle support for inputs, outputs, attributes, reactive forms and expressions binding evaluation.
4
+
5
+ <details>
6
+ <summary>Compatibility with Angular</summary>
7
+
8
+ | Angular | ng-dynamic-component | NPM package |
9
+ | ------- | -------------------- | ----------------------------- |
10
+ | 17.2.x | 1.x.x | `fg-dynamic-component@^1.0.2` |
11
+ | 17.2.x | 1.x.x | `fg-dynamic-component@^1.0.1` |
12
+
13
+ </details>
14
+
15
+ ## Installation
16
+
17
+ ```bash
18
+ $ npm install fg-dynamic-component --save
19
+ ```
20
+
21
+ ## Usage
22
+
23
+ ### FGDynamicComponent
24
+
25
+ Import `FGDynamicComponent` where you need to render dynamic components:
26
+
27
+ ```ts
28
+ import { FGDynamicComponent } from "fg-dynamic-component";
29
+
30
+ @NgModule({
31
+ imports: [FGDynamicComponent]
32
+ })
33
+ export class MyModule {}
34
+ ```
35
+
36
+ Then in your component's template include `<fg-dynamic>` where you want to render component
37
+ and bind from your component class type of component to render:
38
+
39
+ ```ts
40
+ import { FGDynamicService, FGDynamicItem } from "fg-dynamic-component";
41
+
42
+ FGDynamicService.registerComponent("MyDynamicComponent1", MyDynamicComponent1);
43
+ FGDynamicService.registerComponent(
44
+ "MyDynamicComponent4",
45
+ import("...").then((m) => m.MyDynamicComponent4)
46
+ );
47
+
48
+ @Component({
49
+ selector: "my-component",
50
+ template: `<fg-dynamic [configuration]="configuration()" />`
51
+ })
52
+ class MyComponent {
53
+ configuration = signal({
54
+ type: "MyDynamicComponent1",
55
+ items: [
56
+ {
57
+ type: MyDynamicComponent2
58
+ },
59
+ {
60
+ type: import("...").then((m) => m.MyDynamicComponent3)
61
+ },
62
+ {
63
+ type: "MyDynamicComponent4"
64
+ }
65
+ ]
66
+ } as FGDynamicItem);
67
+ }
68
+ ```
69
+
70
+ #### Standalone API
71
+
72
+ You may use `<fg-dynamic>` as a standalone component:
73
+
74
+ ```ts
75
+ import { FGDynamicComponent, FGDynamicService, FGDynamicItem } from "fg-dynamic-component";
76
+
77
+ FGDynamicService.registerComponent("MyDynamicComponent1", MyDynamicComponent1);
78
+ FGDynamicService.registerComponent(
79
+ "MyDynamicComponent4",
80
+ import("...").then((m) => m.MyDynamicComponent4)
81
+ );
82
+
83
+ @Component({
84
+ selector: "my-component",
85
+ template: `<fg-dynamic [configuration]="configuration()" />`,
86
+ imports: [FGDynamicComponent],
87
+ standalone: true
88
+ })
89
+ class MyComponent {
90
+ configuration = signal({
91
+ type: "MyDynamicComponent1",
92
+ items: [
93
+ {
94
+ type: MyDynamicComponent2
95
+ },
96
+ {
97
+ type: import("...").then((m) => m.MyDynamicComponent3)
98
+ },
99
+ {
100
+ type: "MyDynamicComponent4"
101
+ }
102
+ ]
103
+ } as FGDynamicItem);
104
+ }
105
+ ```
106
+
107
+ _NOTE:_ You can declare components to dynamically load in static and/or dynamic way using or not the FGDynamicService.
108
+
109
+ ### Inputs and Outputs
110
+
111
+ You can pass `inputs` and `outputs` to your dynamic components:
112
+
113
+ ```ts
114
+ @Component({
115
+ selector: "my-component",
116
+ template: `<fg-dynamic [configuration]="configuration()" />`,
117
+ imports: [FGDynamicComponent],
118
+ standalone: true
119
+ })
120
+ class MyComponent {
121
+ configuration = signal({
122
+ type: MyDynamicComponent1,
123
+ inputs: {
124
+ hello: "world",
125
+ something: () => "can be really complex"
126
+ },
127
+ outputs: {
128
+ onSomething: (type) => alert(type)
129
+ }
130
+ } as FGDynamicItem);
131
+ }
132
+
133
+ @Component({
134
+ selector: "my-dynamic-component1",
135
+ template: "Dynamic Component 1"
136
+ })
137
+ class MyDynamicComponent1 {
138
+ @Input()
139
+ hello: string;
140
+ @Input()
141
+ something: Function;
142
+ @Output()
143
+ onSomething = new EventEmitter<string>();
144
+ }
145
+ ```
146
+
147
+ You can update your inputs passing expressions binding using a view model and they will trigger standard Angular's life-cycle hooks
148
+ (of course you should consider which change detection strategy you are using).
149
+
150
+ ```ts
151
+ @Component({
152
+ selector: 'my-component',
153
+ template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" />`,
154
+ imports: [FGDynamicComponent],
155
+ standalone: true
156
+ })
157
+ class MyComponent {
158
+ configuration = signal({
159
+ type: MyDynamicComponent1,
160
+ inputs: {
161
+ hello: '$vm().count % 2 === 0 ? $vm().message : \'Hello World!\''
162
+ },
163
+ outputs: {
164
+ onSomething: '$vm.update(viewModel => { ...viewModel, message: $event, count: viewModel.count + 1 })'
165
+ }
166
+ } as FGDynamicItem);
167
+ viewModel = model({ message: 'Hello World!', count: 0 });
168
+ }
169
+
170
+ @Component({
171
+ selector: 'my-dynamic-component1',
172
+ template: 'Dynamic Component 1'
173
+ })
174
+ class MyDynamicComponent1 {
175
+ @Input()
176
+ hello: string;
177
+ @Input()
178
+ something: Function;
179
+ @Output()
180
+ onSomething = new EventEmitter<string>();
181
+ }
182
+ ```
183
+
184
+ ### Attributes
185
+
186
+ You can declaratively set attributes, as you would inputs.
187
+
188
+ ```ts
189
+ @Component({
190
+ selector: "my-component",
191
+ template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" />`
192
+ })
193
+ class MyComponent {
194
+ configuration = signal({
195
+ type: MyDynamicComponent1,
196
+ attributes: {
197
+ "my-attribute": "attribute-value",
198
+ class: "some classes",
199
+ disabled: "$vm().isDisabled"
200
+ }
201
+ } as FGDynamicItem);
202
+ viewModel = model({ isDisabled: true });
203
+ }
204
+ ```
205
+
206
+ ### Reactive Forms
207
+
208
+ You can declaratively set attributes to activate model binding, form control status (enabled/disabled) and validations with your ControlValueAccessor components.
209
+
210
+ > **Attributes**:
211
+ >
212
+ >- name: used to attach the new control to the input form group (must match the view model property name).
213
+ >- disabled: specifies that an input field should be disabled.
214
+ >- maxlength: specifies the maximum number of characters allowed in an input field.
215
+ >- minlength: specifies the minimum number of characters allowed in an input field.
216
+ >- min: specifies the minimum value for an input field.
217
+ >- max: specifies the maximum value for an input field.
218
+ >- pattern: specifies a regular expression that the input field's value is checked against.
219
+ >- required: specifies that an input field must be filled.
220
+ >- email: defines a field automatically validated to ensure it is a properly formatted e-mail address.
221
+
222
+ ```ts
223
+ @Component({
224
+ selector: "my-component",
225
+ template: `<fg-dynamic [configuration]="configuration()" [(viewModel)]="viewModel" [formGroup]="formGroup()" />`
226
+ })
227
+ class MyComponent {
228
+ configuration = signal({
229
+ type: MyDynamicComponent1,
230
+ attributes: {
231
+ name: "data.firstName",
232
+ disabled: "$vm().metadata.firstName.disabled",
233
+ maxlength: 20,
234
+ required: true
235
+ }
236
+ } as FGDynamicItem);
237
+ viewModel = model({ data: { firstName: "Jhon" }, metadata: { firstName: { disabled: false } } });
238
+ formGroup = signal(new FormGroup({}));
239
+ }
240
+ ```
241
+
242
+ ## Contributing
243
+
244
+ You are welcome to contribute to this project.
245
+ Simply follow the [contribution guide](/CONTRIBUTING.md).
246
+
247
+ ## License
248
+
249
+ MIT © [Francesco Guagnano](guagnanofrancesco11@gmail.com)