fg-dynamic-component 2.0.0 → 4.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.
@@ -1,119 +1,404 @@
1
- import * as i0 from '@angular/core';
2
- import { OnChanges, OnDestroy, InputSignal, Type, ModelSignal } from '@angular/core';
3
- import { FormGroup } from '@angular/forms';
4
-
5
- interface IFGDynamicItem {
6
- type?: string | Type<unknown> | Promise<Type<unknown>> | (() => Promise<Type<unknown>>);
7
- inputs?: Record<string, string | unknown>;
8
- outputs?: Record<string, string | Function>;
9
- attributes?: Record<string, string | unknown>;
10
- items?: IFGDynamicItem[];
1
+ import * as i0 from "@angular/core";
2
+ import { InputSignal, ModelSignal, OnChanges, OnDestroy, Signal, SimpleChanges, Type } from "@angular/core";
3
+ import { FormGroup } from "@angular/forms";
4
+ export type FGDynamicType = Type<unknown> | Promise<Type<unknown>> | (() => Promise<Type<unknown>>);
5
+ export interface IFGDynamicItem {
6
+ type?: string | FGDynamicType;
7
+ inputs?: Record<string, unknown>;
8
+ outputs?: Record<string, string | Function>;
9
+ attributes?: Record<string, unknown>;
10
+ items?: IFGDynamicItem[];
11
+ }
12
+ /**
13
+ * Controls what expressions may do. By default expressions are read-only and
14
+ * can only call native built-ins and `$vm()`; custom view-model methods and
15
+ * view-model mutation require an explicit opt-in.
16
+ */
17
+ export interface IFGDynamicExpressionPolicy {
18
+ /** Allow calling any method reachable from the view model. Defaults to `false`. */
19
+ allowCustomMethods?: boolean;
20
+ /** Method names that may be called when `allowCustomMethods` is `false`. */
21
+ allowedMethods?: readonly string[];
22
+ /** Expose `$vm.set` and `$vm.update`. Defaults to `false`. */
23
+ allowViewModelMutation?: boolean;
24
+ }
25
+ /**
26
+ * Controls how the dynamic component interacts with the host `FormGroup`.
27
+ * By default pre-existing controls and nested groups are not reused.
28
+ */
29
+ export interface IFGDynamicFormPolicy {
30
+ /** Reuse controls/groups that already exist in the supplied `FormGroup`. */
31
+ allowExistingControls?: boolean;
32
+ /** Optional allowlist of form control names (the evaluated `attributes.name`). */
33
+ allowedControlNames?: readonly string[];
34
+ }
35
+ /**
36
+ * Controls which component `type` values are accepted.
37
+ * Promise/loader values are rejected unless explicitly enabled.
38
+ */
39
+ export interface IFGDynamicTypePolicy {
40
+ /** Allow promise-returning and function loader `type` values. Defaults to `false`. */
41
+ allowFunctionTypes?: boolean;
42
+ /** Require an explicit scoped registry instead of the global default. */
43
+ requireScopedRegistry?: boolean;
44
+ }
45
+ /**
46
+ * Controls which DOM attributes may be applied. `strict` is intended for
47
+ * untrusted configurations and disables UI-redress/DOM-clobbering attributes.
48
+ */
49
+ export interface IFGDynamicAttributePolicy {
50
+ /** Disallow `id`, `class`, `for`, `href` and `src`. Defaults to `false`. */
51
+ strict?: boolean;
52
+ }
53
+ /**
54
+ * A scoped component registry. Backed by a `Map`, so lookups never walk the
55
+ * prototype chain and names such as `__proto__` or `constructor` are ordinary keys.
56
+ *
57
+ * Use one registry per rendering context (e.g. per plugin or tenant) so a
58
+ * configuration can only select components that were explicitly registered for
59
+ * that context.
60
+ */
61
+ export declare class FGDynamicRegistry {
62
+ private readonly _components;
63
+ register(name: string, type: FGDynamicType): void;
64
+ get(name: string): FGDynamicType | undefined;
65
+ has(name: string): boolean;
66
+ unregister(name: string): boolean;
67
+ clear(): void;
68
+ get names(): string[];
11
69
  }
12
70
  /**
13
71
  * Declare components to dynamically load in static and/or dynamic way using the FGDynamicService.
72
+ *
73
+ * The static registry is global. For untrusted or multi-tenant configurations,
74
+ * create a scoped registry with `FGDynamicService.createRegistry()` and pass it
75
+ * to `<fg-dynamic [registry]="registry">`.
14
76
  */
15
- declare class FGDynamicService {
16
- private static _components;
17
- static registerComponent(name: string, type: Type<unknown> | Promise<Type<unknown>> | (() => Promise<Type<unknown>>)): void;
18
- static getComponent(name: string): Type<unknown> | Promise<Type<unknown>> | (() => Promise<Type<unknown>>);
77
+ export declare class FGDynamicService {
78
+ private static readonly _defaultRegistry;
79
+ static get registry(): FGDynamicRegistry;
80
+ static createRegistry(): FGDynamicRegistry;
81
+ static registerComponent(name: string, type: FGDynamicType): void;
82
+ static getComponent(name: string): FGDynamicType | undefined;
83
+ static hasComponent(name: string): boolean;
84
+ static unregisterComponent(name: string): boolean;
85
+ static clearRegistry(): void;
19
86
  }
20
87
  /**
21
88
  * Create a standalone signals based dynamic components tree through a JSON configuration with full
22
89
  * life-cycle support for inputs, outputs, attributes, reactive forms and expressions binding evaluation.
23
90
  */
24
- declare class FGDynamicComponent implements OnChanges, OnDestroy {
25
- configuration: InputSignal<IFGDynamicItem>;
26
- viewModel: ModelSignal<unknown>;
27
- formGroup: InputSignal<FormGroup>;
28
- private _viewContainerRef;
29
- private _dynamicItems;
30
- private _componentRef;
31
- private _renderer;
32
- private _outputsSubscriptions;
33
- private _formControl;
34
- private _formControlDirective;
35
- private _formControlSubscription;
36
- private _managedValidatorFns;
37
- private _component;
38
- private _injector;
39
- /**
40
- * A callback method that is invoked immediately after the default change
41
- * detector has checked data-bound properties if at least one has changed,
42
- * and before the view and content children are checked.
43
- */
44
- ngOnChanges(): Promise<void>;
45
- /**
46
- * A method to lazy-load a component.
47
- */
48
- private loadComponentAsync;
49
- /**
50
- * Instantiates a single component and inserts its host view into this container.
51
- */
52
- private createComponent;
53
- /**
54
- * Register handlers for those events by subscribing to an instance.
55
- */
56
- private handleOutputs;
57
- /**
58
- * Construct a FormControl with an initial value.
59
- */
60
- private createFormControl;
61
- /**
62
- * Disables/enables the control.
63
- */
64
- private setFormControlStatus;
65
- /**
66
- * Add synchronous validators to this control.
67
- */
68
- private setFormControlValidators;
69
- /**
70
- * Synchronizes a standalone FormControl instance to a form control element.
71
- */
72
- private attachFormControlDirective;
73
- /**
74
- * Gets the value at path of object. If the resolved value is undefined, the defaultValue is returned in its place.
75
- * @param model The object.
76
- * @param property The path.
77
- * @param defaultValue The resolved value.
78
- */
79
- private getModelPropertyValue;
80
- /**
81
- * Sets the value at path of object. If a portion of path doesn't exist, it's created.
82
- * Arrays are created for missing index properties while objects are created for all other missing properties.
83
- * This method mutates object.
84
- * @param model The object.
85
- * @param property The path.
86
- * @param value The value.
87
- */
88
- private setModelPropertyValue;
89
- /**
90
- * Updates specified input names to new values.
91
- */
92
- private setInputs;
93
- /**
94
- * Set attribute values for an element in the DOM.
95
- */
96
- private setAttributes;
97
- /**
98
- * Evaluates JavaScript code and executes it.
99
- * @param value The JavaScript code.
100
- * @param $vm The view model.
101
- * @param $event The event.
102
- * @returns Evaluated expression.
103
- */
104
- private evaluateExpression;
105
- /**
106
- * Cleans up every dynamically created resource: subscriptions, form control, value accessor directive and component reference.
107
- * Used both on component type change and on destroy.
108
- */
109
- private cleanup;
110
- /**
111
- * A callback method that performs custom clean-up, invoked immediately before a directive, pipe, or service instance is destroyed.
112
- */
113
- ngOnDestroy(): void;
114
- static ɵfac: i0.ɵɵFactoryDeclaration<FGDynamicComponent, never>;
115
- static ɵcmp: i0.ɵɵComponentDeclaration<FGDynamicComponent, "fg-dynamic", never, { "configuration": { "alias": "configuration"; "required": true; "isSignal": true; }; "viewModel": { "alias": "viewModel"; "required": false; "isSignal": true; }; "formGroup": { "alias": "formGroup"; "required": false; "isSignal": true; }; }, { "viewModel": "viewModelChange"; }, never, never, true, never>;
116
- }
117
-
118
- export { FGDynamicComponent, FGDynamicService };
119
- export type { IFGDynamicItem };
91
+ export declare class FGDynamicComponent implements OnChanges, OnDestroy {
92
+ configuration: InputSignal<IFGDynamicItem>;
93
+ viewModel: ModelSignal<unknown>;
94
+ formGroup: InputSignal<FormGroup>;
95
+ registry: InputSignal<FGDynamicRegistry>;
96
+ expressionPolicy: InputSignal<IFGDynamicExpressionPolicy>;
97
+ formControlPolicy: InputSignal<IFGDynamicFormPolicy>;
98
+ typePolicy: InputSignal<IFGDynamicTypePolicy>;
99
+ attributePolicy: InputSignal<IFGDynamicAttributePolicy>;
100
+ /** Current nesting depth; used to bound recursive configurations. */
101
+ depth: InputSignal<number>;
102
+ /**
103
+ * Validated child items. Invalid entries are ignored and the list is capped
104
+ * to avoid pathological configurations blocking the renderer.
105
+ */
106
+ protected readonly items: Signal<readonly IFGDynamicItem[]>;
107
+ private _viewContainerRef;
108
+ private _dynamicItems;
109
+ private _componentRef?;
110
+ private _renderer;
111
+ private _outputsSubscriptions;
112
+ private _currentOutputsConfig?;
113
+ private _formControl?;
114
+ private _formControlDirective?;
115
+ private _formControlSubscription?;
116
+ private _managedValidatorFns;
117
+ private _component?;
118
+ private _injector;
119
+ private _ngOnChangesCounter;
120
+ private _lastProjectedItemsSignature?;
121
+ /** Group that literally contains the current control (may be a nested group). */
122
+ private _formControlContainer?;
123
+ /** Literal key of the control inside `_formControlContainer`. */
124
+ private _formControlKey?;
125
+ /** True only when this component created (and may therefore remove) the control. */
126
+ private _ownsFormControl;
127
+ /** Intermediate groups created while wiring a dotted control name. */
128
+ private _createdFormGroups;
129
+ /** Form wiring currently attached to the rendered component, used to detect rebinds. */
130
+ private _wiredFormGroup?;
131
+ private _wiredControlName?;
132
+ /** Disabled state managed by this component, so it can be restored when `disabled` disappears. */
133
+ private _disabledManaged;
134
+ private _disabledBeforeManagement?;
135
+ /** Attribute names currently applied to the dynamic element. */
136
+ private _appliedAttributes;
137
+ /** Input names currently set on the dynamic component. */
138
+ private _appliedInputs;
139
+ /**
140
+ * A callback method that is invoked immediately after the default change
141
+ * detector has checked data-bound properties if at least one has changed,
142
+ * and before the view and content children are checked.
143
+ */
144
+ ngOnChanges(changes?: SimpleChanges): Promise<void>;
145
+ /**
146
+ * Destroys the rendered component when it no longer has a resolvable type.
147
+ * Ignored when a newer `ngOnChanges` generation has started.
148
+ */
149
+ private clearResolvedComponent;
150
+ /**
151
+ * Validates the whole configuration subtree before rendering. Rejects
152
+ * excessive depth, node count, key counts, oversized keys and cycles.
153
+ * The check is iterative so a hostile configuration cannot overflow the
154
+ * JavaScript stack during validation itself.
155
+ */
156
+ private validateConfiguration;
157
+ private collectConfigurationStats;
158
+ /**
159
+ * A method to lazy-load a component.
160
+ */
161
+ private loadComponentAsync;
162
+ private isPromiseLike;
163
+ private resolveCandidate;
164
+ private toComponentType;
165
+ private isAngularComponentType;
166
+ /**
167
+ * Function loaders and thenables execute host code, so they are only
168
+ * accepted when the host opts in. Angular component classes stay allowed.
169
+ */
170
+ private isCandidateAllowed;
171
+ private isUsingGlobalRegistry;
172
+ private getRegistry;
173
+ /**
174
+ * Instantiates a single component and inserts its host view into this container.
175
+ */
176
+ private createComponent;
177
+ /**
178
+ * Register handlers for those events by subscribing to an instance.
179
+ * Supports both `EventEmitter` (`@Output`) and signal outputs created with `output()`.
180
+ */
181
+ private handleOutputs;
182
+ private isOutputEmitter;
183
+ private handleOutputsIfChanged;
184
+ /**
185
+ * Evaluates the configured `attributes.name` into a safe control path.
186
+ * Returns `undefined` when the view model or name is not available yet, so
187
+ * the wiring is retried on the next change.
188
+ */
189
+ private resolveFormControlName;
190
+ /**
191
+ * Recreates the dynamic component when the `formGroup`, the evaluated
192
+ * control name or the availability of the view model changed.
193
+ */
194
+ private rewireFormIfNeeded;
195
+ /**
196
+ * Constructs (or reuses) the form control and attaches it to the rendered
197
+ * component. Dotted names are represented as nested `FormGroup`s so that
198
+ * `formGroup.get('data.firstName')` works and no key contains a dot.
199
+ */
200
+ private wireFormControl;
201
+ /**
202
+ * Walks/creates the nested `FormGroup`s required by a dotted control path.
203
+ * Created groups are tracked so they can be removed again on cleanup.
204
+ */
205
+ private ensureFormGroupPath;
206
+ /**
207
+ * Keeps the view model in sync with the control value. Used for both newly
208
+ * created and reused controls.
209
+ */
210
+ private bindFormControlValueChanges;
211
+ /**
212
+ * Deep-clones arrays and plain objects, preserving functions and non-plain
213
+ * objects by reference. Handles cycles through a `WeakMap`.
214
+ */
215
+ private cloneForMutation;
216
+ private setControlDisabled;
217
+ /**
218
+ * Restores the disabled state a control had before this component managed
219
+ * it (important for pre-existing/reused controls and removed `disabled` keys).
220
+ */
221
+ private restoreManagedDisabledState;
222
+ /**
223
+ * Disables/enables the control, normalizing boolean-ish values, and restores
224
+ * the previous state when the `disabled` key is removed.
225
+ */
226
+ private setFormControlStatus;
227
+ /**
228
+ * Add synchronous validators to this control.
229
+ */
230
+ private setFormControlValidators;
231
+ /**
232
+ * Builds a defensive `pattern` validator. Invalid, oversized or potentially
233
+ * catastrophic regular expressions are ignored instead of blocking the UI.
234
+ */
235
+ private createPatternValidator;
236
+ /**
237
+ * Conservative scanner for regular expressions with nested/ambiguous
238
+ * quantifiers (e.g. `(a+)+`, `(\d+(?:\d+)?)+`, `(a*)*`, `(\d+){2,}`) and
239
+ * quantified alternations (e.g. `(a|aa)+`, `(\w|\d)+`) that can cause
240
+ * exponential backtracking.
241
+ *
242
+ * Groups are tracked with an explicit stack, so nested groups and optional
243
+ * inner quantifiers are detected instead of relying on a single regex.
244
+ * This is still a heuristic: it errs on the side of rejecting ambiguous
245
+ * constructs rather than allowing a catastrophic pattern through.
246
+ */
247
+ private isUnsafeRegex;
248
+ /**
249
+ * Synchronizes a standalone FormControl instance to a form control element.
250
+ */
251
+ private attachFormControlDirective;
252
+ /**
253
+ * Parses a dot/bracket path. Returns `null` when the path is malformed or
254
+ * contains prototype-related segments (`__proto__`, `prototype`,
255
+ * `constructor`), which protects both the view model and `FormGroup`.
256
+ */
257
+ private parsePath;
258
+ /**
259
+ * Strictly parses `a.b`, `a[0]`, `a['b']` and `a["b"]`. Unbalanced brackets,
260
+ * empty segments and stray characters are rejected instead of being silently
261
+ * ignored.
262
+ */
263
+ private parseStringPath;
264
+ private isSafePath;
265
+ private defineOwn;
266
+ /**
267
+ * Only plain objects and arrays may be traversed/written by form
268
+ * synchronization. This prevents writes into class instances, services and
269
+ * DOM objects referenced by the view model.
270
+ */
271
+ private isMutableContainer;
272
+ /**
273
+ * Gets the value at path of object. If the resolved value is undefined, the defaultValue is returned in its place.
274
+ * Only own properties are read; prototype-chain reads are blocked.
275
+ * @param model The object.
276
+ * @param property The path.
277
+ * @param defaultValue The resolved value.
278
+ */
279
+ private getModelPropertyValue;
280
+ /**
281
+ * Sets the value at path of object. If a portion of path doesn't exist, it's created.
282
+ * Arrays are created for missing index properties while objects are created for all other missing properties.
283
+ * Only own properties are traversed and written; prototype-related segments are rejected.
284
+ * This method mutates object.
285
+ * @param model The object.
286
+ * @param property The path.
287
+ * @param value The value.
288
+ */
289
+ private setModelPropertyValue;
290
+ /**
291
+ * Updates specified input names to new values and resets inputs that were
292
+ * removed from the configuration.
293
+ */
294
+ private setInputs;
295
+ /**
296
+ * Set attribute values for an element in the DOM.
297
+ *
298
+ * Attribute names and values are validated: event handlers (`on*`),
299
+ * namespaced attributes, `style`/`srcdoc`/`formaction` and unsafe URL
300
+ * schemes are never applied. Non-primitive values are ignored so that
301
+ * configuration data cannot invoke `toString()`/`toJSON()` hooks.
302
+ *
303
+ * Attributes removed from the configuration (or set to a false boolean /
304
+ * `null`) are removed from the element.
305
+ */
306
+ private setAttributes;
307
+ private isAllowedAttribute;
308
+ /**
309
+ * Returns `undefined` to skip the attribute entirely, `null` to remove it,
310
+ * or a safe string value.
311
+ */
312
+ private attributeValueToString;
313
+ private isSafeUrl;
314
+ /**
315
+ * Evaluates a configured attribute value and reports whether it is an
316
+ * expression that could not be evaluated because its context was missing.
317
+ */
318
+ private evaluateAttribute;
319
+ /**
320
+ * True when a string expression was returned verbatim because its `$vm` or
321
+ * `$event` context was not available. Such values must not be treated as
322
+ * literal booleans/attributes/control names.
323
+ */
324
+ private isUnresolvedExpression;
325
+ /**
326
+ * Normalizes boolean-ish configuration values. `false`, `'false'`, `0`,
327
+ * `'0'`, `''`, `null` and `undefined` are false; everything else is true.
328
+ */
329
+ private toBoolean;
330
+ /**
331
+ * Evaluates an expression with a small, allowlisted interpreter. No `eval`,
332
+ * `Function` or other string-to-code primitive is used.
333
+ * @param value The expression or literal value.
334
+ * @param viewModelValue The resolved view model value.
335
+ * @param eventParam The event payload.
336
+ * @param hasEventContext Whether an event is currently being handled. This
337
+ * distinguishes "no event" from an output that emitted `null`/`undefined`.
338
+ * @returns Evaluated expression, `undefined` when the expression is rejected,
339
+ * or the original value when it is a literal/unresolved expression.
340
+ */
341
+ private evaluateExpression;
342
+ private getViewModelValue;
343
+ private logWarning;
344
+ private logError;
345
+ /**
346
+ * Cleans up every dynamically created resource: subscriptions, form control, value accessor directive and component reference.
347
+ * Used both on component type change and on destroy.
348
+ */
349
+ private cleanup;
350
+ /**
351
+ * A callback method that performs custom clean-up, invoked immediately before a directive, pipe, or service instance is destroyed.
352
+ */
353
+ ngOnDestroy(): void;
354
+ static ɵfac: i0.ɵɵFactoryDeclaration<FGDynamicComponent, never>;
355
+ static ɵcmp: i0.ɵɵComponentDeclaration<FGDynamicComponent, "fg-dynamic", never, {
356
+ "configuration": {
357
+ "alias": "configuration";
358
+ "required": true;
359
+ "isSignal": true;
360
+ };
361
+ "viewModel": {
362
+ "alias": "viewModel";
363
+ "required": false;
364
+ "isSignal": true;
365
+ };
366
+ "formGroup": {
367
+ "alias": "formGroup";
368
+ "required": false;
369
+ "isSignal": true;
370
+ };
371
+ "registry": {
372
+ "alias": "registry";
373
+ "required": false;
374
+ "isSignal": true;
375
+ };
376
+ "expressionPolicy": {
377
+ "alias": "expressionPolicy";
378
+ "required": false;
379
+ "isSignal": true;
380
+ };
381
+ "formControlPolicy": {
382
+ "alias": "formControlPolicy";
383
+ "required": false;
384
+ "isSignal": true;
385
+ };
386
+ "typePolicy": {
387
+ "alias": "typePolicy";
388
+ "required": false;
389
+ "isSignal": true;
390
+ };
391
+ "attributePolicy": {
392
+ "alias": "attributePolicy";
393
+ "required": false;
394
+ "isSignal": true;
395
+ };
396
+ "depth": {
397
+ "alias": "depth";
398
+ "required": false;
399
+ "isSignal": true;
400
+ };
401
+ }, {
402
+ "viewModel": "viewModelChange";
403
+ }, never, never, true, never>;
404
+ }