ngx-dynamic-entity 2.0.2 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-dynamic-entity",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Angular standalone UI library for rendering dynamic entity forms.",
   "//typings": "Local workspace resolution only: ng-packagr 21 writes types/ngx-dynamic-entity.d.ts into dist/package.json. Do NOT add a 'main' field here — ng-packagr does not generate one, so it would be copied verbatim and resolve wrongly in the published package.",
   "typings": "types/ngx-dynamic-entity.d.ts",
@@ -8,7 +8,7 @@
     "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/forms": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
-    "@dynamic-entity/core": "^2.0.2",
+    "@dynamic-entity/core": "^2.1.1",
     "rxjs": "^7.0.0"
   },
   "keywords": [

package/types/ngx-dynamic-entity.d.ts

@@ -286,9 +286,8 @@ interface ImportTransport {
      * choice — and `spec` is that selection already expanded against the config. A transport that
      * renders locally wants the spec; one that asks a server wants the selection, because the
      * server has the config and only the choice needs to cross the wire. Passing both means
-     * neither has to reconstruct the other: the HTTP transport used to recover the selection from
-     * the expanded spec, which worked only because `stripIndices` happens to be exactly the
-     * inverse of the expansion. Optional, so an existing implementation keeps compiling.
+     * neither has to reconstruct the other. Optional, so an existing implementation keeps
+     * compiling.
      */
     template(spec: TemplateSpec, format: TemplateFormat, context: ImportContext, fields?: readonly string[]): Promise<Blob>;
 }
@@ -465,7 +464,7 @@ declare const ENTITY_REF_CACHE_STORE: InjectionToken<EntityRefCacheStore>;
 declare const SYSTEM_DEFAULT_CAN_EDIT: InjectionToken<(roles: string[]) => boolean>;
 type ConfigSourceHandler = (entityKey: string) => any;
 /**
- * Registry/Resolver for resolving an EntityFormConfig by entity key across entities (Phase 8).
+ * Registry/Resolver for resolving an EntityFormConfig by entity key across entities.
  * Enables cross-entity field referencing (`isReferenced`, `referencedEntityKey`, `referencedFieldId`, `hasDrift`).
  */
 declare const CONFIG_SOURCE: InjectionToken<ConfigSourceHandler>;
@@ -493,8 +492,7 @@ declare const MARKDOWN_RENDERER: InjectionToken<(source: string) => string>;
  *
  * Masking is presentational — see SECURITY.md — and what it prints is a product decision:
  * `••••••••` reads as a redaction, "Hidden" reads as a permission, and a localized string
- * reads as neither in English. It was a literal repeated across every field component, so
- * there was no way to choose.
+ * reads as neither in English, so it is the host's to choose.
  *
  * @example
  * { provide: MASKED_PLACEHOLDER, useValue: '••••••••' }
@@ -709,10 +707,9 @@ declare class ValidatorRegistryService {
     /**
      * Say when a named validator resolved to nothing.
      *
-     * It used to be dropped in silence, which is the worst failure mode this library has: the
-     * schema says the field is checked, the field is not checked, the form saves, and nothing
-     * anywhere said so. For `customAsync` that is typically a uniqueness check, so the duplicate
-     * lands in the database.
+     * Silence would be the worst failure mode this library has: the schema says the field is
+     * checked, the field is not checked, the form saves, and nothing says so. For
+     * `customAsync` that is typically a uniqueness check, so the duplicate lands in the database.
      *
      * Dev only, once per name — this runs while controls are built, which happens on every
      * config change. `validateConfig` with `knownValidators` is the build-time version of the
@@ -1000,13 +997,8 @@ interface RuleSyncContext {
 /**
  * RulesEvaluationService — evaluates rules, and owns what a result *means*.
  *
- * It used to be two passthrough methods, with the interpretation spread across the component:
- * the render filter decided one way what a rule result did to a field, and the validity sync
- * decided again forty lines further down. They disagreed about what "every field" meant, and
- * the consequence was a required field inside a `group` that a rule had hidden holding
- * `form.invalid` true forever with nothing on screen to explain it.
- *
- * Precedence lives here now, in one method that both callers go through. Still stateless —
+ * Precedence lives in one method that both the render filter and the validity sync go
+ * through, so what is on screen and what counts toward validity cannot disagree. Stateless —
  * every method takes the result it is interpreting, so there is nothing to go stale against a
  * rebuilt form and nothing to reset between configs.
  */
@@ -1081,9 +1073,7 @@ declare class ConfigSourceService {
 /**
  * Resolves an Angular `ValidationErrors` object to the message shown under a field.
  *
- * These strings used to be hardcoded English literals inside each field component, so a
- * German form meant re-implementing every field type — the labels honoured `language` while
- * the errors underneath them did not.
+ * Field components never hardcode these strings, so errors honour `language` just as labels do.
  *
  * A message is a plain string, or a function when it needs the error's own detail
  * (`minlength.requiredLength`, `min.min`, and so on). The active `language` is passed
@@ -1119,12 +1109,10 @@ declare class ValidationMessagesService {
     /**
      * The message for a field, chosen by its **type** rather than by a list the caller supplies.
      *
-     * Every field component used to pass its own copy of the key order, and the copies were
-     * near-identical — which was tolerable while the field itself was the only thing that
-     * rendered a message. It stopped being tolerable when the error summary above the form
-     * started naming what is wrong with each field: the summary has no field component to ask
-     * (the offending field is usually on a tab that is not rendered), so it would have needed a
-     * second copy of the same table, and a dropdown would have said "This field is required" in
+     * Both the field itself and the error summary above the form render this message, and the
+     * summary has no field component to ask (the offending field is usually on a tab that is
+     * not rendered). Per-component key orders would drift, and a dropdown would say "This
+     * field is required" in
      * the summary and "Please select an option" under the control.
      *
      * One table, read from both places, is what keeps those two sentences the same sentence.
@@ -1314,8 +1302,7 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /**
      * Whether the current roles may see this record at all.
      *
-     * `permissions.view` used to be computed and thrown away — a user whose roles failed it
-     * still received the complete form with every value in the DOM. It is honoured now.
+     * A user whose roles fail `permissions.view` gets no form, so no value reaches the DOM.
      *
      * As with masking, this is presentational: it stops the browser rendering data, it does
      * not stop the data reaching the browser. Authorize on the server.
@@ -1359,13 +1346,11 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /**
      * Whether the Save button is unavailable.
      *
-     * This used to be `submitBlocked`, so an invalid form greyed Save out — and a greyed button
-     * is the worst possible answer to "why can't I save?". It cannot be clicked, so there is no
-     * moment at which the form gets to say which field is at fault or which tab it is on; the
-     * user is left comparing a disabled button against a form that looks, to them, filled in.
-     * On a tabbed form the offending field is usually not even on screen.
+     * Deliberately not `submitBlocked`: a greyed button is the worst answer to "why can't I
+     * save?". It cannot be clicked, so the form never gets to say which field is at fault or
+     * which tab it is on — and on a tabbed form that field is usually not on screen.
      *
-     * Save now stays available while the form is merely invalid. Clicking it still saves
+     * Save stays available while the form is merely invalid. Clicking it still saves
      * nothing — `submit()` checks `submitBlocked` and refuses — but the refusal is where the
      * error summary, the tab badges and the jump to the first bad field come from, so pressing
      * Save produces an explanation instead of silence.
@@ -1535,25 +1520,10 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /**
      * Ids already warned about, per component instance.
      *
-     * This was `private static`, so it was module-global mutable state that nothing ever
-     * cleared: under SSR every render of every form in the process accumulated into one set
-     * that lived as long as the server did, and the first request to render a config
-     * suppressed the warning for every request after it. Per instance, the warning is once per
-     * form — which is what "warn once" was meant to mean.
+     * Per instance, never `static`: under SSR a module-global set would outlive every request,
+     * and the first render of a config would suppress the warning for every render after it.
      */
     private readonly warnedAmbiguousIds;
-    /**
-     * The value map rules and `showWhen` are evaluated against.
-     *
-     * Every field appears under two keys: its bare id, and its `refererField` path wrapped in brackets.
-     * The bare id is what every config written so far uses and is kept exactly as it was — but
-     * ids are unique per scope, so when two scopes define one the last field walked wins and
-     * the rule reads whichever that is. `[personal.address]` names one field and cannot be
-     * ambiguous, which is why a rule that has to distinguish them uses the ref.
-     *
-     * Both live in one flat map on purpose: `evaluateFormRules` takes a `Record<string,
-     * unknown>` and needs no knowledge of refs at all — the extra keys simply resolve.
-     */
     /**
      * Every name a rule may address this field by.
      *
@@ -1579,28 +1549,16 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /**
      * Every field in the config with the scope its value is stored under, cached per config.
      *
-     * `collectFieldScopes` walks the whole tree. It was called once per field from `pathFor`,
-     * which `namesField` calls, which the render filter calls for every field on the active
-     * tab — a quadratic walk on every change-detection pass. Keyed by config identity, so a
+     * `collectFieldScopes` walks the whole tree, and `pathFor` runs once per rendered field on
+     * every change-detection pass — uncached, that is quadratic. Keyed by config identity, so a
      * new config invalidates it without an explicit lifecycle hook to forget.
      */
     private fieldScopes;
     private scopeEntryFor;
     private scopeCache?;
-    /**
-     * The control a scope entry addresses, named by path rather than by bare id.
-     *
-     * `getControl(field.id)` with no tab falls through to a first-match recursive search of the
-     * whole form, so with `address` on two tabs, hiding one disabled the other. The control
-     * tree mirrors the scope path exactly — `buildTabControls` nests by tab id and
-     * `buildFieldControl` nests a `group` under its own id — so a `[path]` ref resolves through
-     * `form.get()` on `getControl`'s first branch and names exactly one control.
-     *
-     * A field inside an `array` has no static path: its controls live in `FormArray` rows built
-     * per row. `form.get()` returns null for those and they are left alone, which is correct —
-     * a row's controls are created and destroyed with the row.
-     */
+    /** The control a scope entry addresses — see `FormStructureService.controlAt`. */
     private controlForEntry;
+    /** The value map rules and `showWhen` are evaluated against — see `FormStructureService.flattenValues`. */
     private flattenFormValues;
     /**
      * `autoPatch` — copy mapped fields out of the record the user just selected in an
@@ -1610,8 +1568,18 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /**
      * `patchOnTrue` — when a boolean/checkbox field transitions to `true`,
      * copy `from` → `to` within the current record.
+     *
+     * The trigger is read by its ref, and a bare `from`/`to` resolves to a sibling in the
+     * trigger's own scope before falling back to a form-wide lookup — so two groups that each
+     * carry `home`, `billing` and a "same as" flag patch within themselves, not across.
      */
     private runPatchOnTrue;
+    /**
+     * A field named by a mapping, preferring a sibling in `scope` when the name is a bare id.
+     *
+     * `key` is the field's entry in the flattened value map; `control` is the control it owns.
+     */
+    private resolveInScope;
     /**
      * Prefer a control declared on the configured target tab; fall back to a top-level control.
      *
@@ -1851,10 +1819,8 @@ declare class DynamicRecordFormComponent implements OnChanges {
     /**
      * What this record is called, as opposed to what kind of thing it is.
      *
-     * The header used to show the entity's name twice — "clients", with "Entity: clients"
-     * underneath — so the one question a record header exists to answer, *which* record am I
-     * looking at, was the one thing it did not say. The entity keeps the subtitle; this takes
-     * the heading.
+     * A record header exists to answer *which* record am I looking at, so this takes the
+     * heading and the entity name keeps the subtitle.
      *
      * The order is deliberate. `showOnMinimize` is the author saying "this is what identifies a
      * record" — it is what the summary panel and the collapsed view already show — so it is
@@ -1913,11 +1879,6 @@ declare class DynamicRecordFormComponent implements OnChanges {
     rowDrawerTitle(field: NestedFieldConfig): string;
     /** Summary values render through the shared core formatter, not a local stringifier. */
     formatFieldValue(field: NestedFieldConfig): string;
-    /**
-     * Finds which tab — and, where the field lives one level down, which sub-tab — owns a
-     * field. The walk used to check top-level `fields` only, so every field in a sub-tab was
-     * simply not found and the jump did nothing at all.
-     */
     /**
      * Switches to the tab holding `fieldId`, then scrolls it into view and moves focus to it.
      *
@@ -1987,7 +1948,7 @@ declare class DynamicFieldComponent implements OnChanges, OnDestroy {
      *
      * `detectChanges()` rather than `markForCheck()`: a selection that arrives from a native
      * `change` event (or Playwright) may not be followed by another Angular tick, so a dirty
-     * flag would never be flushed. Running CD on the hosted component now is the copy showing up.
+     * flag would never be flushed. Running CD on the hosted component immediately is what shows the copied value.
      *
      * Done here rather than in each of the eighteen field components: the host owns the
      * component reference, so one subscription covers every type including custom ones.
@@ -2512,12 +2473,6 @@ declare class TextareaFieldComponent {
     masked: boolean;
     get label(): string;
     get placeholder(): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2595,12 +2550,6 @@ declare class MarkdownFieldComponent implements OnChanges {
      */
     private cached?;
     protected rendered(): string | null;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2656,12 +2605,6 @@ declare class CurrencyFieldComponent {
     get placeholder(): string;
     /** Picks the currency symbol from the locale — defaults to '$'. */
     get symbol(): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2689,12 +2632,6 @@ declare class EmailFieldComponent {
     masked: boolean;
     get label(): string;
     get placeholder(): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2726,12 +2663,6 @@ declare class PasswordFieldComponent {
     get label(): string;
     get placeholder(): string;
     toggleVisibility(): void;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2759,12 +2690,6 @@ declare class CheckboxFieldComponent {
     readonly: boolean;
     masked: boolean;
     get label(): string;
-    /**
-     * Configured messages reach this field too.
-     *
-     * It rendered no error element at all, so a required checkbox left unticked told the user
-     * nothing — and `validationMessages` could not reach a field that never displayed one.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2797,12 +2722,6 @@ declare class BooleanFieldComponent {
     readonly: boolean;
     masked: boolean;
     get label(): string;
-    /**
-     * Configured messages reach this field too.
-     *
-     * It rendered no error element at all, so a required checkbox left unticked told the user
-     * nothing — and `validationMessages` could not reach a field that never displayed one.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2831,22 +2750,12 @@ declare class DateFieldComponent {
     /**
      * ISO 8601 date → display string, through the formatter the host configured.
      *
-     * This used to call `toLocaleDateString()` directly, which meant `setDateFormatters` — the
-     * one seam for choosing how a date is rendered — reached the record summary and the `time`
-     * field but not this one. A host that configured formatters got them almost everywhere,
-     * and silently did not get them on the field type most likely to be the reason they
-     * configured formatters at all.
+     * Never call `toLocaleDateString()` directly here: `setDateFormatters` is the one seam for
+     * choosing how a date renders, and every date display has to go through it.
      *
-     * The default formatter is `toLocaleDateString()` with no locale, so an application that
-     * has not called `setDateFormatters` renders exactly what it rendered before.
+     * The default formatter is `toLocaleDateString()` with no locale.
      */
     formatDate(value: string | null): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2897,12 +2806,6 @@ declare class DateTimeFieldComponent {
      * handed on as ISO rather than the raw value.
      */
     formatDateTime(value: unknown): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2942,12 +2845,6 @@ declare class TimeFieldComponent {
      * another in the record summary because the two drifted apart.
      */
     formatTime(value: unknown): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -2990,12 +2887,6 @@ declare class MonthYearFieldComponent {
     onMonthChange(month: string): void;
     onYearChange(year: string): void;
     formatValue(value: unknown): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -3038,10 +2929,7 @@ declare class DropdownFieldComponent {
      * The value this option stores — the option object itself.
      *
      * Kept as a method rather than binding `option` straight into the template, because it is
-     * the one place that says *why* the two are the same thing. It used to delegate to
-     * `getOptionStoredValue`, an exported identity function whose two branches returned their
-     * argument unchanged; naming a transformation that does not happen is worse than naming
-     * nothing, because a reader has to go and check.
+     * the one place that says *why* the two are the same thing.
      */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
@@ -3095,10 +2983,7 @@ declare class RadioFieldComponent implements OnDestroy {
      * The value this option stores — the option object itself.
      *
      * Kept as a method rather than binding `option` straight into the template, because it is
-     * the one place that says *why* the two are the same thing. It used to delegate to
-     * `getOptionStoredValue`, an exported identity function whose two branches returned their
-     * argument unchanged; naming a transformation that does not happen is worse than naming
-     * nothing, because a reader has to go and check.
+     * the one place that says *why* the two are the same thing.
      */
     getOptStoredVal(option: DropdownOption): unknown;
     /**
@@ -3121,12 +3006,6 @@ declare class RadioFieldComponent implements OnDestroy {
     isChecked(option: DropdownOption): boolean;
     /** Read-only display — synchronous, per §6.2. See `DropdownFieldComponent.getLabel`. */
     getSelectedLabel(): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -3166,21 +3045,12 @@ declare class MultiSelectFieldComponent {
      * The value this option stores — the option object itself.
      *
      * Kept as a method rather than binding `option` straight into the template, because it is
-     * the one place that says *why* the two are the same thing. It used to delegate to
-     * `getOptionStoredValue`, an exported identity function whose two branches returned their
-     * argument unchanged; naming a transformation that does not happen is worse than naming
-     * nothing, because a reader has to go and check.
+     * the one place that says *why* the two are the same thing.
      */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
     /** Read-only display — synchronous, per §6.2. See `DropdownFieldComponent.getLabel`. */
     getLabels(values: unknown): string;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */
@@ -3243,12 +3113,6 @@ declare class EntityRefFieldComponent implements OnInit {
     private parentValue;
     /** Reload (and drop a stale selection) whenever the parent control changes. */
     private watchParent;
-    /**
-     * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
-     * validationMessages })` reaches this field. It used to render a fixed
-     * "This field has an error", which made a documented, configurable feature work on three
-     * of fifteen field types.
-     */
     /** Author help text, shown under the control and named by `aria-describedby`. */
     get hint(): string;
     /** The ids of whatever is describing this control right now. */