fg-dynamic-component 1.1.1 → 3.0.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 CHANGED
@@ -7,6 +7,8 @@ Create an Angular standalone signals based dynamic components tree through a JSO
7
7
 
8
8
  | Angular | fg-dynamic-component | NPM package |
9
9
  | ------- | -------------------- | ----------------------------- |
10
+ | 22.2.3 | 3.0.0 | `fg-dynamic-component@^3.0.0` |
11
+ | 22.1.6 | 2.0.0 | `fg-dynamic-component@^2.0.0` |
10
12
  | 17.2.4 | 1.1.1 | `fg-dynamic-component@^1.1.1` |
11
13
  | 17.2.4 | 1.1.0 | `fg-dynamic-component@^1.1.0` |
12
14
  | 17.2.4 | 1.0.2 | `fg-dynamic-component@^1.0.2` |
@@ -39,7 +41,7 @@ Then in your component's template include `<fg-dynamic>` where you want to rende
39
41
  and bind from your component class type of component to render:
40
42
 
41
43
  ```ts
42
- import { FGDynamicService, FGDynamicItem } from "fg-dynamic-component";
44
+ import { FGDynamicService, IFGDynamicItem } from "fg-dynamic-component";
43
45
 
44
46
  FGDynamicService.registerComponent("MyDynamicComponent1", MyDynamicComponent1);
45
47
  FGDynamicService.registerComponent("MyDynamicComponent4", import("...").then(m => m.MyDynamicComponent4));
@@ -72,7 +74,7 @@ class MyComponent {
72
74
  type: () => import("...").then(m => m.MyDynamicComponent7)
73
75
  }
74
76
  ]
75
- } as FGDynamicItem);
77
+ } as IFGDynamicItem);
76
78
  }
77
79
  ```
78
80
 
@@ -81,7 +83,7 @@ class MyComponent {
81
83
  You may use `<fg-dynamic>` as a standalone component:
82
84
 
83
85
  ```ts
84
- import { FGDynamicComponent, FGDynamicService, FGDynamicItem } from "fg-dynamic-component";
86
+ import { FGDynamicComponent, FGDynamicService, IFGDynamicItem } from "fg-dynamic-component";
85
87
 
86
88
  FGDynamicService.registerComponent("MyDynamicComponent4", import("...").then(m => m.MyDynamicComponent4));
87
89
  FGDynamicService.registerComponent("MyDynamicComponent5", async () => (await import("...")).MyDynamicComponent5);
@@ -114,12 +116,40 @@ class MyComponent {
114
116
  type: () => import("...").then(m => m.MyDynamicComponent7)
115
117
  }
116
118
  ]
117
- } as FGDynamicItem);
119
+ } as IFGDynamicItem);
118
120
  }
119
121
  ```
120
122
 
121
123
  _NOTE:_ You can declare components to dynamically load in static and/or dynamic way using or not the FGDynamicService.
122
124
 
125
+ #### Scoped registry
126
+
127
+ `FGDynamicService` uses a global registry. When configurations are not fully trusted
128
+ (for example multi-tenant or plugin scenarios), create a scoped registry and pass it
129
+ to the component. Scoped registries are propagated to nested items as well:
130
+
131
+ ```ts
132
+ import { FGDynamicComponent, FGDynamicRegistry, FGDynamicService } from "fg-dynamic-component";
133
+
134
+ const registry: FGDynamicRegistry = FGDynamicService.createRegistry();
135
+ registry.register("MyDynamicComponent1", MyDynamicComponent1);
136
+
137
+ @Component({
138
+ selector: "my-component",
139
+ template: `<fg-dynamic [configuration]="configuration()" [registry]="registry" />`,
140
+ imports: [FGDynamicComponent],
141
+ standalone: true
142
+ })
143
+ class MyComponent {
144
+ registry = registry;
145
+ configuration = signal({ type: "MyDynamicComponent1" });
146
+ }
147
+ ```
148
+
149
+ A configuration can only resolve component names that were explicitly registered in
150
+ the registry it receives. Names such as `constructor`, `__proto__` or `toString` are
151
+ never resolved from the registry prototype chain.
152
+
123
153
  ### Inputs and Outputs
124
154
 
125
155
  You can pass `inputs` and `outputs` to your dynamic components:
@@ -141,7 +171,7 @@ class MyComponent {
141
171
  outputs: {
142
172
  onSomething: (type) => alert(type)
143
173
  }
144
- } as FGDynamicItem);
174
+ } as IFGDynamicItem);
145
175
  }
146
176
 
147
177
  @Component({
@@ -175,10 +205,14 @@ class MyComponent {
175
205
  hello: '$vm().count % 2 === 0 ? $vm().message : \'Hello World!\''
176
206
  },
177
207
  outputs: {
178
- onSomething: '$vm.update(viewModel => { ...viewModel, message: $event, count: viewModel.count + 1 })'
208
+ onSomething: '$vm().handleSomething($event)'
179
209
  }
180
- } as FGDynamicItem);
181
- viewModel = model({ message: 'Hello World!', count: 0 });
210
+ } as IFGDynamicItem);
211
+ viewModel = model({
212
+ message: 'Hello World!',
213
+ count: 0,
214
+ handleSomething: (value: string) => { /* ... */ }
215
+ });
182
216
  }
183
217
 
184
218
  @Component({
@@ -208,15 +242,27 @@ class MyComponent {
208
242
  configuration = signal({
209
243
  type: MyDynamicComponent1,
210
244
  attributes: {
211
- "my-attribute": "attribute-value",
245
+ "data-my-attribute": "attribute-value",
212
246
  class: "some classes",
213
247
  disabled: "$vm().isDisabled"
214
248
  }
215
- } as FGDynamicItem);
249
+ } as IFGDynamicItem);
216
250
  viewModel = model({ isDisabled: true });
217
251
  }
218
252
  ```
219
253
 
254
+ > **Allowed attributes**
255
+ >
256
+ > Only a safe allowlist of attributes is applied: `id`, `class`, `name`, `role`,
257
+ > `title`, `tabindex`, `hidden`, `dir`, `lang`, `for`, `href`, `src`, the common
258
+ > form attributes (`disabled`, `readonly`, `required`, `placeholder`, …) and any
259
+ > `data-*` or `aria-*` attribute.
260
+ >
261
+ > Event handlers (`on*`), `style`, `srcdoc`, `formaction`, namespaced attributes
262
+ > and non-primitive values are ignored. `href` and `src` only accept `http`,
263
+ > `https`, `mailto`, `tel` and relative URLs, so `javascript:` URLs are blocked
264
+ > even when they come from an expression.
265
+
220
266
  ### Reactive Forms
221
267
 
222
268
  You can declaratively set attributes to activate model binding, form control status (enabled/disabled) and validations with your ControlValueAccessor components.
@@ -247,12 +293,62 @@ class MyComponent {
247
293
  maxlength: 20,
248
294
  required: true
249
295
  }
250
- } as FGDynamicItem);
296
+ } as IFGDynamicItem);
251
297
  viewModel = model({ data: { firstName: "Jhon" }, metadata: { firstName: { disabled: false } } });
252
298
  formGroup = signal(new FormGroup({}));
253
299
  }
254
300
  ```
255
301
 
302
+ > **Security note**
303
+ >
304
+ > `disabled` and the form validators are configured by the same configuration that
305
+ > renders the form. They are **UX-only**: a client can always bypass them. Never use
306
+ > them for authorization or as the only validation layer. Enforce permissions,
307
+ > required fields, ranges and formats again on the server.
308
+ >
309
+ > Control names are interpreted as dot/bracket paths into the view model. Paths that
310
+ > contain `__proto__`, `prototype` or `constructor` are rejected, so a configuration
311
+ > cannot pollute object prototypes or register such names in a `FormGroup`.
312
+
313
+ ## Security
314
+
315
+ ### Expressions are interpreted, never evaluated
316
+
317
+ `inputs`, `outputs` and `attributes` values that contain `$vm` or `$event` are
318
+ evaluated by a small, self-contained interpreter. No `eval`, `new Function` or
319
+ other string-to-code primitive is used. The supported subset is:
320
+
321
+ - literals (`'text'`, `42`, `true`, `false`, `null`, `undefined`), arrays and objects;
322
+ - member access `$vm().name`, `$vm()['name']` and optional chaining `$vm().a?.b`;
323
+ - calls such as `$vm().save($event)` and expression-bodied arrow functions
324
+ (for example `$vm().items.map(item => item.id)`);
325
+ - unary, arithmetic, comparison, logical, nullish and ternary operators;
326
+ - array/object spread and arrow functions whose body returns an expression or
327
+ contains a `return` statement.
328
+
329
+ Anything else is ignored at runtime (a warning is printed only in development mode).
330
+ In particular globals (`window`, `fetch`, …), assignments, `new`, `this`, template
331
+ literals, regular-expression literals and access to `__proto__`, `prototype`,
332
+ `constructor`, `caller`, `callee` or `arguments` are rejected. Expressions are also
333
+ limited in size, token count, nesting depth and evaluation steps.
334
+
335
+ A value that contains neither `$vm` nor `$event` is used as a plain literal.
336
+
337
+ > Expressions are configuration data, not sandboxed user code: a trusted
338
+ > configuration can still call methods that exist on the view model. Only load
339
+ > configurations from sources you trust.
340
+
341
+ ### Other hardening
342
+
343
+ - Attribute names/values are validated (see [Attributes](#attributes)) and URL
344
+ schemes are checked.
345
+ - The component registry uses a `Map` and never resolves inherited properties
346
+ (`constructor`, `__proto__`, …). Prefer a scoped registry for untrusted
347
+ configurations.
348
+ - Angular component classes are never invoked as loader functions.
349
+ - Dev-mode diagnostics never include expression sources, configuration values or
350
+ raw error objects.
351
+
256
352
  ## Contributing
257
353
 
258
354
  You are welcome to contribute to this project.