fg-dynamic-component 1.0.1 → 1.1.0

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