@processpuzzle/base-entity 1.4.0 → 1.5.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.
@@ -2,11 +2,10 @@ import * as i0 from "@angular/core";
2
2
  import { AfterViewInit, EnvironmentProviders, InjectionToken, Injector, InputSignal, OnDestroy, OnInit, PipeTransform, Provider, ProviderToken, Signal, TemplateRef, Type, ViewContainerRef, WritableSignal } from "@angular/core";
3
3
  import { FormControl, FormGroup } from "@angular/forms";
4
4
  import { NGXLogger } from "ngx-logging-kit";
5
- import { ActivatedRouteSnapshot, CanActivateFn, Route, Routes } from "@angular/router";
6
- import { WritableStateSource } from "@ngrx/signals";
7
- import { MatTableDataSource } from "@angular/material/table";
8
- import { DocumentData, DocumentSnapshot, Firestore, WhereFilterOp, collection, deleteDoc, doc, getDoc, getDocs, limit, orderBy, query, setDoc, updateDoc, where } from "@angular/fire/firestore";
5
+ import { ActivatedRouteSnapshot, CanActivateFn, CanDeactivateFn, Route, Routes } from "@angular/router";
9
6
  import { Observable } from "rxjs";
7
+ import "@ngrx/signals";
8
+ import { MatTableDataSource } from "@angular/material/table";
10
9
  import { MatSnackBar } from "@angular/material/snack-bar";
11
10
  import { HttpClient, HttpContext, HttpHeaders } from "@angular/common/http";
12
11
  import { CdkDragDrop } from "@angular/cdk/drag-drop";
@@ -18,6 +17,7 @@ import { MatPaginator } from "@angular/material/paginator";
18
17
  import { SelectionModel } from "@angular/cdk/collections";
19
18
  import { ReleaseState, TranslationSource } from "@processpuzzle/util";
20
19
  import "reflect-metadata";
20
+ import { MatDialogRef } from "@angular/material/dialog";
21
21
  export declare enum FormControlType {
22
22
  ADDITIONAL_PROPERTIES = "ADDITIONAL_PROPERTIES",
23
23
  /**
@@ -27,6 +27,11 @@ export declare enum FormControlType {
27
27
  ADDRESS = "ADDRESS",
28
28
  ARTIFACT = "ARTIFACT",
29
29
  AVATAR = "AVATAR",
30
+ /**
31
+ * A value a calculation derives. Read-only; shows what the calculation would produce from the form's unsaved
32
+ * state. Rendered by the component registered under `ENTITY_CALCULATED_CONTROL`, a plain label without one.
33
+ */
34
+ CALCULATED = "CALCULATED",
30
35
  CHECKBOX = "CHECKBOX",
31
36
  /**
32
37
  * An append-only history of rich-text comments, each stamped with its author and time — the value is an
@@ -66,6 +71,11 @@ export declare abstract class AbstractAttrDescriptor {
66
71
  attrName: string;
67
72
  formControlType: FormControlType;
68
73
  disabled: boolean;
74
+ /**
75
+ * Editable only while the entity is new: a key chosen at creation, which the entity is then known by. Once it
76
+ * has been saved the control is disabled, so it stays out of the update the same way a read-only attribute does.
77
+ */
78
+ createOnly: boolean;
69
79
  style: {
70
80
  [p: string]: unknown;
71
81
  } | null | undefined;
@@ -100,7 +110,6 @@ interface PersistedBaseEntity extends BaseEntity {
100
110
  readonly id: string;
101
111
  }
102
112
  type PersistedEntity<Entity extends BaseEntity> = Entity & PersistedBaseEntity;
103
- declare function assertPersistedEntity<Entity extends BaseEntity>(entity: Entity): asserts entity is PersistedEntity<Entity>;
104
113
  /**
105
114
  * The named display style of a DATE / DATE_TIME attribute.
106
115
  *
@@ -126,17 +135,8 @@ export declare const DEFAULT_DATE_TIME_FORMAT: Readonly<Required<DateFormat>>;
126
135
  export declare function effectiveDateFormat(attr: {
127
136
  dateFormat?: DateFormat;
128
137
  } | undefined, valueKind?: 'DATE' | 'DATE_TIME'): Required<DateFormat>;
129
- /** Whether the format edits a calendar day only, stored as a local `YYYY-MM-DD` rather than an instant. */
130
- declare function isDateOnly(format: DateFormat): boolean;
131
138
  /** The `Intl.DateTimeFormat` options of a format; a `none` style is left out rather than passed through. */
132
139
  export declare function intlOptionsOf(format: DateFormat): Intl.DateTimeFormatOptions;
133
- /**
134
- * A stored value as a `Date`, or `undefined` when it is not one. A bare `YYYY-MM-DD` is read as *local*
135
- * midnight: `new Date('1960-12-09')` is UTC midnight, which west of Greenwich is the evening before.
136
- */
137
- declare function toDateValue(value: unknown): Date | undefined;
138
- /** A picked date in the shape it is saved in: a local `YYYY-MM-DD` for a date-only format, the instant otherwise. */
139
- declare function toStoredDate(date: Date, format: DateFormat): string | Date;
140
140
  /** Renders `value` in `locale`; a value that is not a date is returned unchanged. */
141
141
  export declare function formatDateValue<T>(value: T, format: DateFormat, locale: string): string | T;
142
142
  /**
@@ -179,7 +179,6 @@ interface PostalAddress {
179
179
  }
180
180
  /** The fields of a {@link PostalAddress} a user types — everything but the country and the location. */
181
181
  type AddressLineField = 'street' | 'addressLine2' | 'postalCode' | 'city' | 'region';
182
- declare const ADDRESS_LINE_FIELDS: readonly AddressLineField[];
183
182
  interface GeoPoint {
184
183
  latitude: number;
185
184
  longitude: number;
@@ -219,6 +218,11 @@ export declare class BaseEntityAttrDescriptor extends AbstractAttrDescriptor {
219
218
  dateFormat?: DateFormat;
220
219
  isLinkToDetails?: boolean;
221
220
  selectables?: SelectablesInput;
221
+ /**
222
+ * `TAGS` only: the key of the `TAG_SUGGESTION_SOURCES` entry that supplies values to pick from. The control
223
+ * still accepts free text; values the source does not know are marked as new.
224
+ */
225
+ tagSuggestions?: string;
222
226
  visible: boolean;
223
227
  showThumbnail?: boolean;
224
228
  /**
@@ -315,6 +319,8 @@ interface EntityTabDescriptor {
315
319
  i18nKey: string;
316
320
  /** Component the route mounts. */
317
321
  component: Type<unknown>;
322
+ /** Leaves out the entity status bar (breadcrumb) while this tab is open — for a tab that brings a header of its own. */
323
+ hideStatusbar?: boolean;
318
324
  /** Suffix for the link's `data-testid`; defaults to `show-<segment>`. */
319
325
  testIdSuffix?: string;
320
326
  /**
@@ -340,6 +346,7 @@ interface BaseEntityDescriptorOptions {
340
346
  entityName: string;
341
347
  entityTitle?: EntityTitle;
342
348
  extraFormActionsTemplate?: ExtraFormActionsTemplate;
349
+ extraListActionsTemplate?: ExtraFormActionsTemplate;
343
350
  /** Screens beyond List and Details. See {@link EntityTabDescriptor}. */
344
351
  extraTabs?: EntityTabDescriptor[];
345
352
  /**
@@ -361,6 +368,20 @@ interface BaseEntityDescriptorOptions {
361
368
  * is about inheritance, and from the preview mode, which is a host's decision about definitions built at run time.
362
369
  */
363
370
  isReadOnly?: boolean;
371
+ /**
372
+ * False for an entity whose rows come into being some other way than the generic New — the users of an
373
+ * organization, who are invited. The toolbar then does not offer New, while edit and delete stay as they
374
+ * are. Defaults to true.
375
+ */
376
+ isCreatable?: boolean;
377
+ /**
378
+ * Whether one row may be changed, decided per entity. A row the server owns outright, an administrator's role
379
+ * for instance, is shown and saved only where this answers true. The form then shows it read-only. Not a
380
+ * kind of row: that is {@link isReadOnly}.
381
+ */
382
+ isEditable?: (entity: BaseEntity) => boolean;
383
+ /** As {@link isEditable}, for the delete action on the row. */
384
+ isDeletable?: (entity: BaseEntity) => boolean;
364
385
  /** Name of the entity this one inherits from. Unrelated to {@link componentParent}. */
365
386
  parentEntity?: string;
366
387
  route?: string;
@@ -380,24 +401,40 @@ interface BaseEntityDescriptorOptions {
380
401
  * without {@link componentParent}, and rejected without it.
381
402
  */
382
403
  isEmbedded?: boolean;
404
+ /**
405
+ * True when a user can pick one object of this entity as the **context object** — the aggregate whose embedded
406
+ * components are then listed and edited without naming it again. Rejected on an embedded entity: it has no
407
+ * object of its own to pick.
408
+ */
409
+ canContextObject?: boolean;
383
410
  }
384
411
  export declare class BaseEntityDescriptor {
385
412
  store: unknown;
413
+ /**
414
+ * Takes a retired row back, when this entity has retired rows (a shared type's deleted records). Assigned by the
415
+ * facade that knows the repository, like {@link store}; the form offers Reinstate on a retired row only if it is set.
416
+ */
417
+ reinstate?: (id: string) => Observable<unknown>;
386
418
  attrDescriptors: AbstractAttrDescriptor[];
387
419
  entityName: string;
388
420
  entityTitle: EntityTitle;
389
421
  extraFormActionsTemplate?: ExtraFormActionsTemplate;
422
+ extraListActionsTemplate?: ExtraFormActionsTemplate;
390
423
  extraTabs: EntityTabDescriptor[];
391
424
  i18nScope?: string;
392
425
  titleKey?: string;
393
426
  parentEntity: string | undefined;
394
427
  readonly isAbstract: boolean;
395
428
  readonly isReadOnly: boolean;
429
+ readonly isCreatable: boolean;
430
+ readonly isEditable: ((entity: BaseEntity) => boolean) | undefined;
431
+ readonly isDeletable: ((entity: BaseEntity) => boolean) | undefined;
396
432
  route: string | undefined;
397
433
  /** Normalized {@link BaseEntityDescriptorOptions.componentParent}; empty when this is not a component. */
398
434
  readonly componentParents: readonly string[];
399
435
  readonly isEmbedded: boolean;
400
- constructor({ store, attrDescriptors, entityName, entityTitle, extraFormActionsTemplate, extraTabs, i18nScope, titleKey, isAbstract, isReadOnly, parentEntity, route, componentParent, isEmbedded }: BaseEntityDescriptorOptions);
436
+ readonly canContextObject: boolean;
437
+ constructor({ store, attrDescriptors, entityName, entityTitle, extraFormActionsTemplate, extraListActionsTemplate, extraTabs, i18nScope, titleKey, isAbstract, isReadOnly, isCreatable, isEditable, isDeletable, parentEntity, route, componentParent, isEmbedded, canContextObject }: BaseEntityDescriptorOptions);
401
438
  createTestId(suffix: string): string;
402
439
  /** Transloco key root for this entity, derived from {@link entityName} unless {@link i18nScope} overrides it. */
403
440
  scopeRoot(): string;
@@ -441,7 +478,7 @@ export declare class BaseEntityDescriptor {
441
478
  * changed, and none of them can tell the difference.
442
479
  *
443
480
  * Compile-time first. A host application that registered a facade did so on purpose — it may carry extra
444
- * tabs, a hand-tuned layout or a Firestore repository — and a definition of the same name does not
481
+ * tabs, a hand-tuned layout or a repository of its own — and a definition of the same name does not
445
482
  * override that decision. The dynamic side is a fallback, in both senses.
446
483
  *
447
484
  * The synthesized side is read out of a cache rather than from the registry that builds it, so that this
@@ -462,18 +499,15 @@ export declare class BaseEntityDescriptorRegistry {
462
499
  static ɵfac: i0.ɵɵFactoryDeclaration<BaseEntityDescriptorRegistry, never>;
463
500
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
464
501
  }
465
- interface WhereCondition<Entity extends BaseEntity> {
466
- field: keyof Entity;
467
- operator: WhereFilterOp;
468
- value: Entity[keyof Entity];
469
- }
502
+ /** The comparison operators a filter condition may use; `toRsql` maps each onto its RSQL/FIQL operator. */
503
+ type FilterOperator = '<' | '<=' | '==' | '!=' | '>=' | '>' | 'array-contains' | 'in' | 'array-contains-any' | 'not-in';
470
504
  interface OrderByCondition<Entity extends BaseEntity> {
471
505
  field: keyof Entity;
472
506
  order?: OrderByDirection;
473
507
  }
474
508
  interface FilterCondition {
475
509
  property: string;
476
- operator: WhereFilterOp;
510
+ operator: FilterOperator;
477
511
  value: string;
478
512
  }
479
513
  type LogicalOperator = 'AND' | 'OR';
@@ -481,7 +515,6 @@ interface FilterGroup {
481
515
  operator: LogicalOperator;
482
516
  conditions: Array<FilterCondition | FilterGroup>;
483
517
  }
484
- declare function isFilterGroup(node: FilterCondition | FilterGroup): node is FilterGroup;
485
518
  export declare enum OrderByDirection {
486
519
  ASC = "asc",
487
520
  DESC = "desc"
@@ -500,15 +533,14 @@ interface BaseEntityQueryCondition {
500
533
  filterGroup?: FilterGroup;
501
534
  orderBys?: OrderBy[];
502
535
  query?: string;
503
- }
504
- interface FirestoreQuery<Entity extends BaseEntity> {
505
- limit?: number;
506
- startAt?: number | string | DocumentSnapshot<Entity>;
507
- startAfter?: number | string | DocumentSnapshot<Entity> | null;
508
- endAt?: number | DocumentSnapshot<Entity>;
509
- endBefore?: number | DocumentSnapshot<Entity>;
510
- orderBy?: OrderByCondition<Entity>[];
511
- where?: WhereCondition<Entity>[];
536
+ /**
537
+ * Read every page and answer them as one, for a screen that works on the whole set (a dashboard) rather than on a
538
+ * page of it behind a pager. Pages are read one after another, `pageSize` (200 when not given) rows each; a bare
539
+ * array answer has no pages and comes back as it is.
540
+ */
541
+ allPages?: boolean;
542
+ /** Also list the retired records of a shared type — the backend honours it for the owner of a record and for the common's own members. */
543
+ includeRetired?: boolean;
512
544
  }
513
545
  interface BaseEntityLoadResponse<Entity extends BaseEntity> {
514
546
  number: number | undefined;
@@ -528,25 +560,6 @@ interface BaseEntityService<Entity extends BaseEntity> {
528
560
  update(entity: PersistedEntity<Entity>): Observable<PersistedEntity<Entity>>;
529
561
  }
530
562
  export declare const BASE_ENTITY_STORE: InjectionToken<unknown>;
531
- interface EntityStoreState<Entity extends BaseEntity> {
532
- entities: Entity[];
533
- number: number;
534
- size: number;
535
- totalElements: number;
536
- totalPages: number;
537
- currentId: string | undefined;
538
- currentEntity: Entity | undefined;
539
- isLoading: boolean;
540
- error: string | undefined;
541
- selectedEntities: Array<Entity>;
542
- /** Keys of rows changed in this store but not yet persisted — see {@link BaseEntityStoreApi.stage}. */
543
- stagedIds: string[];
544
- }
545
- type EntityStoreHandle<Entity extends BaseEntity> = WritableStateSource<EntityStoreState<Entity>> & {
546
- entities: Signal<Entity[]>;
547
- selectedEntities: Signal<Entity[]>;
548
- stagedIds: Signal<string[]>;
549
- };
550
563
  interface BaseEntityStoreApi<Entity extends BaseEntity> {
551
564
  entities: Signal<Entity[]>;
552
565
  selectedEntities: Signal<Entity[]>;
@@ -578,6 +591,8 @@ interface BaseEntityStoreApi<Entity extends BaseEntity> {
578
591
  reload(id: string): Promise<PersistedEntity<Entity> | undefined>;
579
592
  resetErrorState(): void;
580
593
  selectEntity(id: string): void;
594
+ /** What identifies a row of this store — its `id`, or for an embedded row the attribute its entity keys it by. */
595
+ keyOf?(entity: Entity): string | undefined;
581
596
  setCurrentEntity(id: string | undefined): void;
582
597
  /**
583
598
  * Replaces a row in this store **without** persisting it, and remembers that it is unsaved. An embedded
@@ -604,7 +619,6 @@ interface BaseEntityStoreApi<Entity extends BaseEntity> {
604
619
  * its owner's attribute declares. See `EmbeddedEntityFacade`.
605
620
  */
606
621
  type EntityKeyResolver<Entity extends BaseEntity> = (entity: Entity) => string | undefined;
607
- declare const entityKeyById: <Entity extends BaseEntity>(entity: Entity) => string | undefined;
608
622
  export declare function BaseEntityStore<Entity extends BaseEntity>(entityType: new () => Entity, getRepository: () => BaseEntityService<Entity>, keyOf?: EntityKeyResolver<Entity>): import("@ngrx/signals").SignalStoreFeature<import("@ngrx/signals").EmptyFeatureResult, {
609
623
  state: {
610
624
  entities: Entity[];
@@ -628,6 +642,7 @@ export declare function BaseEntityStore<Entity extends BaseEntity>(entityType: n
628
642
  createEntity: () => Entity;
629
643
  add: (entity: Entity) => Promise<PersistedEntity<Entity> | undefined>;
630
644
  delete: (id: string) => Promise<void>;
645
+ keyOf: EntityKeyResolver<Entity>;
631
646
  hasStagedChanges: (id: string) => boolean;
632
647
  deleteAll: import("@ngrx/signals/rxjs-interop").RxMethod<void>;
633
648
  deselectAll: () => void;
@@ -642,10 +657,11 @@ export declare function BaseEntityStore<Entity extends BaseEntity>(entityType: n
642
657
  update: (entity: PersistedEntity<Entity>) => Promise<PersistedEntity<Entity> | undefined>;
643
658
  };
644
659
  }>;
645
- declare class BaseEntityFormBuilder<Entity extends BaseEntity> {
660
+ export declare class BaseEntityFormBuilder<Entity extends BaseEntity> {
646
661
  private readonly logger;
647
662
  private readonly transloco;
648
663
  private readonly stateControl;
664
+ private readonly calculatedControl;
649
665
  buildForm(viewContainerRef: ViewContainerRef, baseEntityForm: FormGroup, store: BaseEntityStoreApi<Entity>, attrDescriptors: AbstractAttrDescriptor[], entity: Signal<Entity>, entityName: string, initialValues?: Record<string, unknown>): void;
650
666
  /**
651
667
  * The tooltip of one control, attached to the control's host element so that every control type — the
@@ -696,8 +712,8 @@ export declare abstract class BaseFormControlComponent<Entity extends BaseEntity
696
712
  responsePayloads: import("@angular/core").Signal<Map<string, import("@processpuzzle/base-entity").NavigationPayload>>;
697
713
  requestPayloads: import("@angular/core").Signal<Map<string, import("@processpuzzle/base-entity").NavigationPayload>>;
698
714
  returnTo: import("@angular/core").Signal<string>;
699
- formSnapshot: import("@angular/core").Signal<Record<string, unknown> | undefined>;
700
- captureFormSnapshot: (snapshot: Record<string, unknown>) => void;
715
+ formSnapshots: import("@angular/core").Signal<Record<string, Record<string, unknown>>>;
716
+ roundTripOpen: import("@angular/core").Signal<boolean>;
701
717
  determineCurrentUrl: () => string;
702
718
  determineOwnerUrl: () => string;
703
719
  determineActiveRouteSegment: () => void;
@@ -714,7 +730,10 @@ export declare abstract class BaseFormControlComponent<Entity extends BaseEntity
714
730
  showsScreenOf: (entityName: string) => boolean;
715
731
  destroyNavigationTracking: () => void;
716
732
  initializeNavigationTracking: () => void;
717
- popFormSnapshot: () => Record<string, unknown> | undefined;
733
+ beginRoundTrip: () => void;
734
+ hasRoundTrip: () => boolean;
735
+ keepFormSnapshot: (owner: string, values: Record<string, unknown>) => void;
736
+ popFormSnapshot: (owner: string) => Record<string, unknown> | undefined;
718
737
  popRequestPayload: (attrName?: string) => import("@processpuzzle/base-entity").NavigationPayload | undefined;
719
738
  popResponsePayload: (attrName?: string) => import("@processpuzzle/base-entity").NavigationPayload | undefined;
720
739
  pushResponsePayload: (payload: import("@processpuzzle/base-entity").NavigationPayload) => void;
@@ -730,7 +749,8 @@ export declare abstract class BaseFormControlComponent<Entity extends BaseEntity
730
749
  responsePayloads: Map<string, import("@processpuzzle/base-entity").NavigationPayload>;
731
750
  requestPayloads: Map<string, import("@processpuzzle/base-entity").NavigationPayload>;
732
751
  returnTo: string;
733
- formSnapshot: Record<string, unknown> | undefined;
752
+ formSnapshots: Record<string, Record<string, unknown>>;
753
+ roundTripOpen: boolean;
734
754
  }>;
735
755
  protected readonly descriptorRegistry: BaseEntityDescriptorRegistry;
736
756
  static ɵfac: i0.ɵɵFactoryDeclaration<BaseFormControlComponent<any>, never>;
@@ -849,7 +869,6 @@ export declare class ObjectStoreService {
849
869
  static ɵfac: i0.ɵɵFactoryDeclaration<ObjectStoreService, never>;
850
870
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
851
871
  }
852
- declare const BASE_ENTITY_MAPPER: InjectionToken<BaseEntityMapper<BaseEntity>>;
853
872
  interface BaseEntityMapper<Entity extends BaseEntity> {
854
873
  fromDto(dto: unknown, index?: number): Entity;
855
874
  toDto(entity: Entity): unknown;
@@ -866,10 +885,8 @@ export declare function getEnumKeyByValue<E>(myEnum: {
866
885
  export declare function getEnumValueByKey<E>(myEnum: {
867
886
  [key: string]: E | string;
868
887
  }, enumKey: string): E | undefined;
869
- type EntityServiceKind = 'rest' | 'firestore';
870
888
  export declare abstract class BaseEntityFacade<Entity extends BaseEntity> {
871
889
  abstract readonly entityType: Type<Entity>;
872
- protected readonly serviceKind: EntityServiceKind;
873
890
  protected readonly endpoint?: string;
874
891
  protected readonly backendRoot?: string;
875
892
  protected readonly injector: Injector;
@@ -928,9 +945,6 @@ export declare class BaseEntityContainerComponent implements OnDestroy, OnInit {
928
945
  };
929
946
  }, {}, never, ["*"], true, never>;
930
947
  }
931
- interface EntityContainerState {
932
- filterKey: string | undefined;
933
- }
934
948
  export declare function BaseEntityContainerStore(): import("@ngrx/signals").SignalStoreFeature<import("@ngrx/signals").EmptyFeatureResult, {
935
949
  state: {
936
950
  filterKey: string | undefined;
@@ -967,7 +981,7 @@ export declare class BaseEntityRestService<Entity extends BaseEntity> implements
967
981
  /**
968
982
  * Reads one entity by id. The `/%{id}` suffix is what makes this a single-entity read: without it the
969
983
  * URL is the collection's, and the response mapper then sees a list where it expects one record — the
970
- * Firestore and embedded implementations of this interface address one document, and so does this one.
984
+ * embedded implementation of this interface addresses one document, and so does this one.
971
985
  */
972
986
  findById(id: string): Observable<void | PersistedEntity<Entity>>;
973
987
  add(entity: Entity, id?: number): Observable<PersistedEntity<Entity>>;
@@ -1022,13 +1036,26 @@ interface RuleEngine {
1022
1036
  evaluate(entity: unknown, rule: EvaluatableRule): RuleEvaluationResult;
1023
1037
  }
1024
1038
  export declare const RULE_ENGINE: InjectionToken<RuleEngine>;
1025
- export declare class BaseEntityFormComponent<Entity extends BaseEntity> implements OnInit, OnDestroy {
1039
+ /** Implemented by a screen that can tell whether leaving it would lose the user's edits. */
1040
+ interface HasUnsavedChanges {
1041
+ /** Resolves true when it is fine to leave — nothing to lose, or the user chose to discard it. */
1042
+ confirmLeave(): boolean | Promise<boolean>;
1043
+ }
1044
+ /** Reminds the user of unsaved changes before they navigate away from an entity form. */
1045
+ export declare const unsavedChangesGuard: CanDeactivateFn<HasUnsavedChanges>;
1046
+ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implements OnInit, OnDestroy, HasUnsavedChanges {
1026
1047
  baseEntityForm: FormGroup;
1027
1048
  entityDescriptor: Signal<BaseEntityDescriptor>;
1028
1049
  entity: Signal<Entity>;
1029
1050
  entityId: InputSignal<string>;
1030
1051
  isAbstract: Signal<boolean>;
1031
1052
  /** A preview of draft definitions over live objects: shown, never saved or deleted — see EntityPreviewMode. */
1053
+ /** The entity-wide read-only state: a kind of row that is never edited, or the preview of a draft. */
1054
+ entityReadOnly: Signal<boolean>;
1055
+ /** Whether the row being shown may be changed; a new entity always may. See {@link BaseEntityDescriptorOptions.isEditable}. */
1056
+ rowEditable: Signal<boolean>;
1057
+ /** Whether the row being shown may be deleted. See {@link BaseEntityDescriptorOptions.isDeletable}. */
1058
+ rowDeletable: Signal<boolean>;
1032
1059
  isReadOnly: Signal<boolean>;
1033
1060
  isNewObject: Signal<boolean>;
1034
1061
  store: Signal<BaseEntityStoreApi<Entity>>;
@@ -1041,6 +1068,11 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1041
1068
  violations: WritableSignal<RuleEvaluationResult[]>;
1042
1069
  hasErrorViolations: Signal<boolean>;
1043
1070
  saveDisabled: Signal<boolean>;
1071
+ /**
1072
+ * Edits made here, or staged in this entity's document by an embedded child or a relationship, that only
1073
+ * this form's Save persists. Read by the status bar indicator and by the leave guard.
1074
+ */
1075
+ hasUnsavedChanges: Signal<boolean>;
1044
1076
  private readonly entityFormBuilder;
1045
1077
  private readonly formBuilder;
1046
1078
  protected readonly formNavigator: {
@@ -1054,8 +1086,8 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1054
1086
  responsePayloads: Signal<Map<string, import("@processpuzzle/base-entity").NavigationPayload>>;
1055
1087
  requestPayloads: Signal<Map<string, import("@processpuzzle/base-entity").NavigationPayload>>;
1056
1088
  returnTo: Signal<string>;
1057
- formSnapshot: Signal<Record<string, unknown> | undefined>;
1058
- captureFormSnapshot: (snapshot: Record<string, unknown>) => void;
1089
+ formSnapshots: Signal<Record<string, Record<string, unknown>>>;
1090
+ roundTripOpen: Signal<boolean>;
1059
1091
  determineCurrentUrl: () => string;
1060
1092
  determineOwnerUrl: () => string;
1061
1093
  determineActiveRouteSegment: () => void;
@@ -1072,7 +1104,10 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1072
1104
  showsScreenOf: (entityName: string) => boolean;
1073
1105
  destroyNavigationTracking: () => void;
1074
1106
  initializeNavigationTracking: () => void;
1075
- popFormSnapshot: () => Record<string, unknown> | undefined;
1107
+ beginRoundTrip: () => void;
1108
+ hasRoundTrip: () => boolean;
1109
+ keepFormSnapshot: (owner: string, values: Record<string, unknown>) => void;
1110
+ popFormSnapshot: (owner: string) => Record<string, unknown> | undefined;
1076
1111
  popRequestPayload: (attrName?: string) => import("@processpuzzle/base-entity").NavigationPayload | undefined;
1077
1112
  popResponsePayload: (attrName?: string) => import("@processpuzzle/base-entity").NavigationPayload | undefined;
1078
1113
  pushResponsePayload: (payload: import("@processpuzzle/base-entity").NavigationPayload) => void;
@@ -1088,12 +1123,18 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1088
1123
  responsePayloads: Map<string, import("@processpuzzle/base-entity").NavigationPayload>;
1089
1124
  requestPayloads: Map<string, import("@processpuzzle/base-entity").NavigationPayload>;
1090
1125
  returnTo: string;
1091
- formSnapshot: Record<string, unknown> | undefined;
1126
+ formSnapshots: Record<string, Record<string, unknown>>;
1127
+ roundTripOpen: boolean;
1092
1128
  }>;
1093
1129
  private readonly logger;
1094
1130
  private readonly ruleEngine;
1095
1131
  private readonly violationsStore;
1096
1132
  private readonly previewMode;
1133
+ private readonly dialog;
1134
+ private readonly unsavedChanges;
1135
+ private unregisterUnsavedChanges;
1136
+ /** Set by Cancel, Delete and a finished Save: leaving is then intended, so the guard stays silent. */
1137
+ private leaveWithoutAsking;
1097
1138
  private rules;
1098
1139
  private readonly fieldsWithRuleErrors;
1099
1140
  private readonly ruleLoad$;
@@ -1102,9 +1143,15 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1102
1143
  ngOnInit(): void;
1103
1144
  ngOnDestroy(): void;
1104
1145
  onCancel(): Promise<void>;
1146
+ /** Whether the row shown is a retired record of a shared type; it can be reinstated where the entity offers it. */
1147
+ isRetired: Signal<boolean>;
1148
+ canReinstate: Signal<boolean>;
1149
+ onReinstate(): Promise<void>;
1105
1150
  onDelete(): Promise<void>;
1106
1151
  onFieldBlur(): void;
1107
1152
  onSubmit(): Promise<void>;
1153
+ /** The route's `canDeactivate` question: asks the user before unsaved changes are thrown away. */
1154
+ confirmLeave(): Promise<boolean>;
1108
1155
  /**
1109
1156
  * Drops the embedded-child changes staged in this entity's document (see `BaseEntityStoreApi.stage`) by
1110
1157
  * re-reading it, so an abandoned edit cannot later pass for a saved one. A new object has no document yet.
@@ -1124,6 +1171,11 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1124
1171
  private applyFieldRuleErrors;
1125
1172
  private clearFieldRuleErrors;
1126
1173
  private loadRules;
1174
+ /**
1175
+ * A key chosen at creation is fixed once the entity exists. Disabled controls are left out of the save, so the
1176
+ * key is not sent again, and the backend keeps the one it stored.
1177
+ */
1178
+ private disableCreateOnlyAttributes;
1127
1179
  private registerEffects;
1128
1180
  static ɵfac: i0.ɵɵFactoryDeclaration<BaseEntityFormComponent<any>, never>;
1129
1181
  static ɵcmp: i0.ɵɵComponentDeclaration<BaseEntityFormComponent<any>, "base-form", never, {
@@ -1134,6 +1186,20 @@ export declare class BaseEntityFormComponent<Entity extends BaseEntity> implemen
1134
1186
  };
1135
1187
  }, {}, never, never, true, never>;
1136
1188
  }
1189
+ /** The suggestion source of the realm's role catalog, for attributes that hold role names. */
1190
+ export declare const REALM_ROLE_SUGGESTIONS = "realm-roles";
1191
+ /**
1192
+ * Where a `TAGS` control gets values to offer, named by the attribute's `tagSuggestions`.
1193
+ *
1194
+ * Suggestions only help: the control still accepts any text, so a source that fails or answers empty
1195
+ * leaves a plain free-text control. base-entity names no source itself — the application binds the ones
1196
+ * it has, with `multi: true`, for example the role catalog under {@link REALM_ROLE_SUGGESTIONS}.
1197
+ */
1198
+ interface TagSuggestionSource {
1199
+ readonly key: string;
1200
+ suggestions(): Observable<readonly string[]>;
1201
+ }
1202
+ export declare const TAG_SUGGESTION_SOURCES: InjectionToken<readonly TagSuggestionSource[]>;
1137
1203
  /**
1138
1204
  * To-many **containment** whose parts live in a table of their own — the child is persisted through its own
1139
1205
  * endpoint and points back at this entity through the foreign key named by
@@ -1195,48 +1261,6 @@ type EmbeddedPath = readonly EmbeddedPathStep[];
1195
1261
  * property is an optional `id`, so TypeScript's weak-type rule rejects exactly those rows.
1196
1262
  */
1197
1263
  type EmbeddedRow = BaseEntity | Record<string, unknown>;
1198
- type Payload = Record<string, unknown>;
1199
- /**
1200
- * An embedded child has no table of its own, so it is addressed by its **position** inside the root's
1201
- * payload — `regions[0].navItems[2]` — rather than by a globally unique id. These functions are the only
1202
- * place that knows how to read and write such a position; everything above them (the service, the list
1203
- * control, the route context) works in terms of a path.
1204
- *
1205
- * They are deliberately free of Angular and of the store: an aggregate is a plain payload, and keeping the
1206
- * arithmetic pure is what makes the nested and id-less cases cheap to test.
1207
- */
1208
- /** Resolves the object a path points at, or `undefined` when any hop is missing. */
1209
- declare function readOwner(root: unknown, path: EmbeddedPath): Payload | undefined;
1210
- /** The rows of one `EMBEDDED_COMPONENTS` attribute; an empty array when the attribute is unset. */
1211
- declare function readRows(root: unknown, path: EmbeddedPath, attrName: string): EmbeddedRow[];
1212
- /**
1213
- * A copy of `root` whose owner carries `rows` under `attrName`, sharing every untouched branch. The
1214
- * aggregate is persisted by replacing the root document wholesale, so a write has to rebuild only the spine
1215
- * from the root down to the owner.
1216
- */
1217
- declare function writeRows(root: unknown, path: EmbeddedPath, attrName: string, rows: readonly EmbeddedRow[]): Payload;
1218
- /**
1219
- * Position of the row identified by `id`, or `-1`. Resolved through {@link rowId} rather than by comparing
1220
- * `id` directly, so that a lookup and the URL segment that arrives back cannot drift apart on an entity
1221
- * keyed by something else — `App Region` has no `id` at all and is identified by `type`.
1222
- */
1223
- declare function indexOfRow(rows: readonly EmbeddedRow[], id: string, referenceIdField?: string): number;
1224
- declare function findRow(rows: readonly EmbeddedRow[], id: string, referenceIdField?: string): EmbeddedRow | undefined;
1225
- /** The value that identifies `row` in a URL segment — its `referenceIdField`, defaulting to `id`. */
1226
- declare function rowId(row: EmbeddedRow, referenceIdField?: string): string;
1227
- declare function appendRow(rows: readonly EmbeddedRow[], row: EmbeddedRow): EmbeddedRow[];
1228
- /** Replaces the row identified by `id`; appends when it is not there yet, so an add and a re-save agree. */
1229
- declare function replaceRow(rows: readonly EmbeddedRow[], id: string, row: EmbeddedRow, referenceIdField?: string): EmbeddedRow[];
1230
- declare function removeRow(rows: readonly EmbeddedRow[], id: string, referenceIdField?: string): EmbeddedRow[];
1231
- /**
1232
- * Moves the row identified by `id` to `toIndex`, shifting the rows in between. The array position *is* the
1233
- * order: every aggregate persists its embedded rows as a JSON array, and the renderers walk it in sequence.
1234
- * Used by an `ordered` list, which saves the result through its owner's form rather than writing it here.
1235
- * An unknown id leaves the rows as they are; `toIndex` is clamped to the array.
1236
- */
1237
- declare function moveRow(rows: readonly EmbeddedRow[], id: string, toIndex: number, referenceIdField?: string): EmbeddedRow[];
1238
- /** Widens a row to the shape the store's API is written in; embedded rows always carry their key field. */
1239
- declare function asPersisted<Entity extends BaseEntity>(row: EmbeddedRow): PersistedEntity<Entity>;
1240
1264
  /**
1241
1265
  * To-many **containment** whose parts have no table of their own — the child's payload travels inside this
1242
1266
  * entity's payload, the way a sub-document does in a document store.
@@ -1272,6 +1296,9 @@ export declare class EmbeddedComponentsListComponent<Entity extends BaseEntity>
1272
1296
  /** The rows as listed: the child store's, in the pending order if the user has rearranged them. */
1273
1297
  readonly rows: Signal<EmbeddedRow[]>;
1274
1298
  /** Only an `ordered` attribute of an editable form offers reordering, and only once there is something to order. */
1299
+ /** Whether the rows are listed. Shown by default; the user may fold a long list away, which changes nothing but the display. */
1300
+ readonly listVisible: import("@angular/core").WritableSignal<boolean>;
1301
+ toggleList(): void;
1275
1302
  readonly reorderable: Signal<boolean>;
1276
1303
  constructor();
1277
1304
  ngOnInit(): void;
@@ -1386,58 +1413,6 @@ export declare class EmbeddedComponentRefComponent {
1386
1413
  "moveDownRequested": "moveDownRequested";
1387
1414
  }, never, never, true, never>;
1388
1415
  }
1389
- /**
1390
- * Hosts the dynamic child form for a single row of an {@link EmbeddedListComponent}.
1391
- */
1392
- declare class EmbeddedListRowComponent<Entity extends BaseEntity> implements OnInit {
1393
- rowHost: ViewContainerRef;
1394
- readonly rowGroup: import("@angular/core").InputSignal<FormGroup<any>>;
1395
- readonly item: import("@angular/core").InputSignal<Record<string, unknown>>;
1396
- readonly childDescriptors: import("@angular/core").InputSignal<AbstractAttrDescriptor[]>;
1397
- readonly store: import("@angular/core").InputSignal<BaseEntityStoreApi<Entity>>;
1398
- readonly formBuilder: import("@angular/core").InputSignal<BaseEntityFormBuilder<Entity>>;
1399
- readonly entityName: import("@angular/core").InputSignal<string>;
1400
- readonly disabled: import("@angular/core").InputSignal<boolean>;
1401
- ngOnInit(): void;
1402
- static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedListRowComponent<any>, never>;
1403
- static ɵcmp: i0.ɵɵComponentDeclaration<EmbeddedListRowComponent<any>, "app-embedded-list-row", never, {
1404
- "rowGroup": {
1405
- "alias": "rowGroup";
1406
- "required": true;
1407
- "isSignal": true;
1408
- };
1409
- "item": {
1410
- "alias": "item";
1411
- "required": false;
1412
- "isSignal": true;
1413
- };
1414
- "childDescriptors": {
1415
- "alias": "childDescriptors";
1416
- "required": true;
1417
- "isSignal": true;
1418
- };
1419
- "store": {
1420
- "alias": "store";
1421
- "required": true;
1422
- "isSignal": true;
1423
- };
1424
- "formBuilder": {
1425
- "alias": "formBuilder";
1426
- "required": true;
1427
- "isSignal": true;
1428
- };
1429
- "entityName": {
1430
- "alias": "entityName";
1431
- "required": true;
1432
- "isSignal": true;
1433
- };
1434
- "disabled": {
1435
- "alias": "disabled";
1436
- "required": false;
1437
- "isSignal": true;
1438
- };
1439
- }, {}, never, never, true, never>;
1440
- }
1441
1416
  interface EmbeddedListItem {
1442
1417
  id: string;
1443
1418
  formGroup: FormGroup;
@@ -1463,58 +1438,6 @@ export declare class EmbeddedListComponent<Entity extends BaseEntity> extends Ba
1463
1438
  static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedListComponent<any>, never>;
1464
1439
  static ɵcmp: i0.ɵɵComponentDeclaration<EmbeddedListComponent<any>, "app-embedded-list", never, {}, {}, never, never, true, never>;
1465
1440
  }
1466
- /**
1467
- * Hosts dynamic child form controls for {@link EmbeddedObjectComponent}.
1468
- */
1469
- declare class EmbeddedObjectBodyComponent<Entity extends BaseEntity> implements OnInit {
1470
- host: ViewContainerRef;
1471
- readonly childGroup: import("@angular/core").InputSignal<FormGroup<any>>;
1472
- readonly item: import("@angular/core").InputSignal<Record<string, unknown>>;
1473
- readonly childDescriptors: import("@angular/core").InputSignal<AbstractAttrDescriptor[]>;
1474
- readonly store: import("@angular/core").InputSignal<BaseEntityStoreApi<Entity>>;
1475
- readonly formBuilder: import("@angular/core").InputSignal<BaseEntityFormBuilder<Entity>>;
1476
- readonly entityName: import("@angular/core").InputSignal<string>;
1477
- readonly disabled: import("@angular/core").InputSignal<boolean>;
1478
- ngOnInit(): void;
1479
- static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedObjectBodyComponent<any>, never>;
1480
- static ɵcmp: i0.ɵɵComponentDeclaration<EmbeddedObjectBodyComponent<any>, "app-embedded-object-body", never, {
1481
- "childGroup": {
1482
- "alias": "childGroup";
1483
- "required": true;
1484
- "isSignal": true;
1485
- };
1486
- "item": {
1487
- "alias": "item";
1488
- "required": false;
1489
- "isSignal": true;
1490
- };
1491
- "childDescriptors": {
1492
- "alias": "childDescriptors";
1493
- "required": true;
1494
- "isSignal": true;
1495
- };
1496
- "store": {
1497
- "alias": "store";
1498
- "required": true;
1499
- "isSignal": true;
1500
- };
1501
- "formBuilder": {
1502
- "alias": "formBuilder";
1503
- "required": true;
1504
- "isSignal": true;
1505
- };
1506
- "entityName": {
1507
- "alias": "entityName";
1508
- "required": true;
1509
- "isSignal": true;
1510
- };
1511
- "disabled": {
1512
- "alias": "disabled";
1513
- "required": false;
1514
- "isSignal": true;
1515
- };
1516
- }, {}, never, never, true, never>;
1517
- }
1518
1441
  /**
1519
1442
  * Renders an embedded object as an inline fieldset whose child controls are built from
1520
1443
  * `config().childDescriptors`.
@@ -1534,62 +1457,6 @@ interface RelatedEntityNameAttr {
1534
1457
  attrName: string;
1535
1458
  name: string;
1536
1459
  }
1537
- declare class RelatedEntityRefComponent<Entity extends BaseEntity, RelatedEntity extends BaseEntity> {
1538
- entity: InputSignal<Entity>;
1539
- relatedEntity: InputSignal<PersistedEntity<RelatedEntity>>;
1540
- relatedEntityNameAttr: InputSignal<RelatedEntityNameAttr>;
1541
- disabled: InputSignal<boolean>;
1542
- /**
1543
- * Which field of a raw row carries the id, when it is not `id` — the owning attribute's
1544
- * `referenceIdField`. Needed on this component and not only on the list, because removal filters the
1545
- * attribute's raw value and has to resolve each item's id the same way the rendering did.
1546
- */
1547
- referenceIdField: InputSignal<string | undefined>;
1548
- formGroup: InputSignal<FormGroup>;
1549
- linkedEntityType: InputSignal<string>;
1550
- private readonly formNavigator;
1551
- relatedEntityName(): string;
1552
- navigateToRelated(event: Event): void;
1553
- removeRelatedEntity(): void;
1554
- static ɵfac: i0.ɵɵFactoryDeclaration<RelatedEntityRefComponent<any, any>, never>;
1555
- static ɵcmp: i0.ɵɵComponentDeclaration<RelatedEntityRefComponent<any, any>, "app-related-entity-ref", never, {
1556
- "entity": {
1557
- "alias": "entity";
1558
- "required": true;
1559
- "isSignal": true;
1560
- };
1561
- "relatedEntity": {
1562
- "alias": "relatedEntity";
1563
- "required": true;
1564
- "isSignal": true;
1565
- };
1566
- "relatedEntityNameAttr": {
1567
- "alias": "relatedEntityNameAttr";
1568
- "required": true;
1569
- "isSignal": true;
1570
- };
1571
- "disabled": {
1572
- "alias": "disabled";
1573
- "required": false;
1574
- "isSignal": true;
1575
- };
1576
- "referenceIdField": {
1577
- "alias": "referenceIdField";
1578
- "required": false;
1579
- "isSignal": true;
1580
- };
1581
- "formGroup": {
1582
- "alias": "formGroup";
1583
- "required": true;
1584
- "isSignal": true;
1585
- };
1586
- "linkedEntityType": {
1587
- "alias": "linkedEntityType";
1588
- "required": true;
1589
- "isSignal": true;
1590
- };
1591
- }, {}, never, never, true, never>;
1592
- }
1593
1460
  /**
1594
1461
  * To-many **association**: the rows point at entities that exist independently of this one, so adding
1595
1462
  * picks an existing entity from the related list and deleting only detaches the reference. Containment —
@@ -1750,7 +1617,7 @@ export declare class EntityUserContext {
1750
1617
  *
1751
1618
  * A static list rather than a seeded entity: the codes are a standard, not tenant data, and the browser
1752
1619
  * already knows every country's name in every language through `Intl.DisplayNames` — so the lookup needs no
1753
- * backend, works the same against REST, json-server and Firestore, and is translated for free.
1620
+ * backend, works the same against REST and json-server, and is translated for free.
1754
1621
  */
1755
1622
  export declare const COUNTRY_CODES: readonly string[];
1756
1623
  interface CountryOption {
@@ -1764,8 +1631,6 @@ export declare function countryName(code: string, language: string): string;
1764
1631
  * runtime rejects gets the codes themselves, in code order.
1765
1632
  */
1766
1633
  export declare function countryOptions(language: string): CountryOption[];
1767
- /** The region of a BCP 47 language tag (`hu-HU` → `HU`), when it names one this list knows. */
1768
- declare function countryOfLanguageTag(tag: string | undefined): string | undefined;
1769
1634
  type AddressFields = {
1770
1635
  country: FormControl<string | null>;
1771
1636
  street: FormControl<string | null>;
@@ -1845,8 +1710,6 @@ interface AddressFieldLayout {
1845
1710
  interface AddressFormat {
1846
1711
  lines: AddressFieldLayout[][];
1847
1712
  }
1848
- /** For a country without a format of its own: every field, international order. */
1849
- declare const DEFAULT_ADDRESS_FORMAT: AddressFormat;
1850
1713
  /** The format of a country, by its ISO 3166-1 alpha-2 code; the international default for any other. */
1851
1714
  export declare function addressFormatOf(country: string | undefined): AddressFormat;
1852
1715
  /**
@@ -2095,6 +1958,71 @@ export declare class LocaleDateAdapter extends NativeDateAdapter {
2095
1958
  * adapter keeps `MAT_DATE_LOCALE`.
2096
1959
  */
2097
1960
  export declare function provideLocaleDateAdapter(): EnvironmentProviders;
1961
+ /** What a route's list is pre-filtered with, as the route declares it. */
1962
+ interface RouteListFilter {
1963
+ /** Raw RSQL the list is always filtered by. */
1964
+ rsqlFilter?: string;
1965
+ /** The working context whose active entity the list can be narrowed to. */
1966
+ filterByContext?: string;
1967
+ }
1968
+ /**
1969
+ * Metadata of a **working context**: an entity the user picks once and then works inside, instead of passing
1970
+ * through List → Form on every visit. Nothing in the platform knows what the entity is — a Customer, a Warehouse,
1971
+ * an Order — it only reads this declaration.
1972
+ *
1973
+ * See `docs/active-entity-concept/working-context-spec.md`.
1974
+ */
1975
+ interface WorkingContextDefinition {
1976
+ /** The context's name, and its URL segment: `ctx/<name>/<id>/...`. Lower-case, no slashes. */
1977
+ name: string;
1978
+ /** Entity type acting as the context root. Any entity with a registered descriptor and store may be named. */
1979
+ entityName: string;
1980
+ /**
1981
+ * True for a **context object**: the entity is an aggregate whose own URL carries the context (`<aggregate>/<id>/<embedded>/list`),
1982
+ * derived from its descriptor's `canContextObject` rather than declared. Such a context has no `ctx` segment, parent or base path.
1983
+ */
1984
+ aggregate?: boolean;
1985
+ /** A parent context. Selecting another parent clears this context, because its routes nest below the parent's. */
1986
+ parent?: string;
1987
+ /**
1988
+ * Absolute path the `ctx/<name>` routes are mounted under, for selecting from a screen outside them — the
1989
+ * entity's own list. Inside a context route the URL already says where it is, and that wins.
1990
+ */
1991
+ basePath?: string;
1992
+ picker?: WorkingContextPicker;
1993
+ display?: WorkingContextDisplay;
1994
+ /**
1995
+ * Conditions on the **active** entity that make switching away from it — or clearing it — ask first. Keys are
1996
+ * attribute names; `state` names the entity's STATE attribute when it has no attribute of that name. A value
1997
+ * may be a list of alternatives. `{ state: 'Running' }`.
1998
+ */
1999
+ confirmSwitchWhen?: Record<string, unknown>;
2000
+ /** `url-local-storage` (default) restores the last context when a context view is opened without one. */
2001
+ persist?: WorkingContextPersistence;
2002
+ }
2003
+ type WorkingContextPersistence = 'url' | 'url-local-storage';
2004
+ interface WorkingContextPicker {
2005
+ /** Attributes the picker's search matches against; the entity's title attribute when omitted. */
2006
+ searchFields?: string[];
2007
+ /** How many recently active entities the picker offers on top. Default 3; 0 turns the section off. */
2008
+ recent?: number;
2009
+ }
2010
+ /** What the status bar shows of the active entity. Templates use `{{attr}}` / `{{attr.nested}}` placeholders. */
2011
+ interface WorkingContextDisplay {
2012
+ /** The crumb's text; the entity's title attribute when omitted. */
2013
+ label?: string;
2014
+ /** Attribute rendered as a badge; `state` names the STATE attribute, as in {@link WorkingContextDefinition.confirmSwitchWhen}. */
2015
+ badge?: string;
2016
+ /** A second, quieter piece of text after the label — the current step, say. */
2017
+ extra?: string;
2018
+ }
2019
+ export declare const DEFAULT_RECENT_CONTEXTS = 3;
2020
+ export declare const WORKING_CONTEXT_DEFINITIONS: InjectionToken<WorkingContextDefinition[][]>;
2021
+ /**
2022
+ * Declares working contexts. May be called more than once — an application and each module it mounts can
2023
+ * contribute their own — and the declarations add up.
2024
+ */
2025
+ export declare function provideWorkingContexts(...definitions: WorkingContextDefinition[]): EnvironmentProviders;
2098
2026
  export declare const BASE_LIST_DESCRIPTORS: InjectionToken<string[]>;
2099
2027
  export declare class BaseEntityListComponent<Entity extends BaseEntity> implements AfterViewInit, OnInit {
2100
2028
  dataSource: MatTableDataSource<PersistedEntity<Entity>>;
@@ -2104,6 +2032,24 @@ export declare class BaseEntityListComponent<Entity extends BaseEntity> implemen
2104
2032
  private readonly formNavigator;
2105
2033
  private readonly objectStoreService;
2106
2034
  private readonly foreignKeyLabels;
2035
+ private readonly route;
2036
+ /** The filters this list's route declares: its RSQL, and the working context it may be narrowed to. */
2037
+ protected readonly routeFilter: RouteListFilter;
2038
+ /** The active entity of the context the list may be narrowed to; `undefined` when none is active. */
2039
+ protected readonly contextEntityId: Signal<string | undefined>;
2040
+ /** Narrowing to the active entity: on by default, as the spec's optional view offers it. */
2041
+ protected readonly onlyActiveContext: import("@angular/core").WritableSignal<boolean>;
2042
+ /** Whether the retired records of a shared type are listed too, marked as such. Off by default, like every list and picker. */
2043
+ protected readonly showRetired: import("@angular/core").WritableSignal<boolean>;
2044
+ /** An entity whose records can be retired is one that can reinstate them: a shared type. */
2045
+ protected readonly canShowRetired: Signal<boolean>;
2046
+ /** Whether the toggle is shown: the list may be narrowed, and there is something to narrow it to. */
2047
+ protected readonly showsContextToggle: Signal<boolean>;
2048
+ /** Set once the first load is made, so that a context change before it does not load twice. */
2049
+ private viewReady;
2050
+ private readonly workingContext;
2051
+ /** The working contexts this entity is the root of. They add a "Set as context object" button below the list, enabled while exactly one row is selected. */
2052
+ protected readonly workingContexts: Signal<WorkingContextDefinition[]>;
2107
2053
  columnDescriptors: Signal<BaseEntityAttrDescriptor[]>;
2108
2054
  displayedColumns: Signal<string[]>;
2109
2055
  sort: MatSort;
@@ -2111,6 +2057,8 @@ export declare class BaseEntityListComponent<Entity extends BaseEntity> implemen
2111
2057
  store: BaseEntityStoreApi<PersistedEntity<Entity>>;
2112
2058
  protected selectOrCreateMode: import("@angular/core").WritableSignal<boolean>;
2113
2059
  private requestPayload?;
2060
+ /** The URL a user was sent away from for lack of a context object, which choosing one continues to; `undefined` otherwise. */
2061
+ protected readonly pendingTarget: Signal<string | undefined>;
2114
2062
  constructor();
2115
2063
  ngAfterViewInit(): void;
2116
2064
  ngOnInit(): void;
@@ -2118,6 +2066,13 @@ export declare class BaseEntityListComponent<Entity extends BaseEntity> implemen
2118
2066
  onNavigateToDetails(entity: PersistedEntity<Entity>): void;
2119
2067
  onNavigateToRelated(config: BaseEntityAttrDescriptor, entity: PersistedEntity<Entity>): void;
2120
2068
  onRowClick(entity: PersistedEntity<Entity>): void;
2069
+ /** Enter on a row of a context entity makes it the active one, as double-click does; elsewhere it selects. */
2070
+ onRowEnter(entity: PersistedEntity<Entity>): void;
2071
+ onRowDoubleClick(entity: PersistedEntity<Entity>): void;
2072
+ onSetActive(definition: WorkingContextDefinition, entity: PersistedEntity<Entity>): Promise<void>;
2073
+ /** Makes the one selected row the context object. */
2074
+ onSetSelectedAsContext(): Promise<void>;
2075
+ canSetContextObject(): boolean;
2121
2076
  /** A FOREIGN_KEY cell shows the linked object's identifying attribute, as the form does, not its id. */
2122
2077
  foreignKeyLabel(config: BaseEntityAttrDescriptor, entity: PersistedEntity<Entity>): string;
2123
2078
  /** An ARTIFACT cell's value as a list: a multi-valued attribute holds an array, a single-valued one an object. */
@@ -2128,10 +2083,17 @@ export declare class BaseEntityListComponent<Entity extends BaseEntity> implemen
2128
2083
  onToggleAllRows(): void;
2129
2084
  onCancelSelectOrCreate(): Promise<void>;
2130
2085
  onSelectEntity(): Promise<void>;
2086
+ /** The row's key as its store knows it: an embedded row is keyed by its `referenceIdField`, which is not always `id`. */
2087
+ private keyOf;
2131
2088
  private cancelSelections;
2132
2089
  private doFilter;
2133
2090
  private getPropertyValue;
2091
+ /** Narrows the list to the active entity, or shows every row of the entity again. */
2092
+ protected onToggleContextFilter(on: boolean): void;
2093
+ protected onToggleRetired(on: boolean): void;
2094
+ protected isRetired(row: unknown): boolean;
2134
2095
  private loadAllData;
2096
+ private rsqlQuery;
2135
2097
  protected registerEffects(): void;
2136
2098
  isAllSelected(): boolean;
2137
2099
  isSelected(row: PersistedEntity<Entity>): boolean;
@@ -2140,10 +2102,6 @@ export declare class BaseEntityListComponent<Entity extends BaseEntity> implemen
2140
2102
  static ɵcmp: i0.ɵɵComponentDeclaration<BaseEntityListComponent<any>, "base-list", never, {}, {}, never, never, true, never>;
2141
2103
  }
2142
2104
  export declare const ACTIVE_ENTITY_FACADE: InjectionToken<BaseEntityFacade<BaseEntity>>;
2143
- interface EntityTabsState {
2144
- activeTabs: string[];
2145
- currentTab: string | undefined;
2146
- }
2147
2105
  export declare function BaseEntityTabsStore(): import("@ngrx/signals").SignalStoreFeature<import("@ngrx/signals").EmptyFeatureResult, {
2148
2106
  state: {
2149
2107
  activeTabs: string[];
@@ -2195,6 +2153,17 @@ export declare class EntityRegistryComponent {
2195
2153
  * only for what an older backend may still answer.
2196
2154
  */
2197
2155
  type EntityDefinitionStatus = 'DRAFT' | 'ACTIVE' | 'DEPRECATED';
2156
+ /** `EntitySharing` of the contract: the policy of a type a common shares with the organizations of its starter. */
2157
+ interface EntitySharing {
2158
+ write: 'COMMON_ADMIN' | 'OWNER_ORG' | 'SELF';
2159
+ visibility: 'PUBLIC' | 'OWNER_ONLY';
2160
+ /** Limits a PUBLIC type: non-owners see a record only in these states of its state machine. */
2161
+ visibleWhen?: {
2162
+ state: string[];
2163
+ };
2164
+ /** The REFERENCE attribute whose record this type's records follow: owner and visibility are that record's. */
2165
+ from?: string;
2166
+ }
2198
2167
  /** `ValueKind` of the contract: what the attribute's value *is*, as opposed to how it is edited. */
2199
2168
  type EntityValueKind = 'TEXT' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATE_TIME' | 'ENUM' | 'REFERENCE';
2200
2169
  /**
@@ -2303,6 +2272,17 @@ export declare class EntityDefinition implements BaseEntity {
2303
2272
  componentParents?: string[];
2304
2273
  /** True when this definition's payload travels inside its parent's and it has no rows of its own. */
2305
2274
  isEmbedded?: boolean;
2275
+ /** True when a user can pick one object of this type as the context object; see `BaseEntityDescriptorOptions.canContextObject`. */
2276
+ canContextObject?: boolean;
2277
+ /** Set on a type of a common: shared with every organization of its starter. Kept as read so a save does not drop it. */
2278
+ sharing?: EntitySharing;
2279
+ /** Natural keys: attribute codes whose values together are unique among the type's non-retired records. Kept as read. */
2280
+ identifiers?: string[][];
2281
+ /**
2282
+ * Set on a type this organization reads but does not own: the key of the common that shares it. Such a type is
2283
+ * released, shown read-only, and neither changed nor deleted from here. Reported by the backend, never sent back.
2284
+ */
2285
+ sharedFrom?: string;
2306
2286
  attributes?: EntityAttributeDefinition[];
2307
2287
  version?: number;
2308
2288
  createdAt?: string;
@@ -2324,17 +2304,10 @@ export declare class EntityDefinition implements BaseEntity {
2324
2304
  interface DynamicEntity {
2325
2305
  id?: string;
2326
2306
  version?: number;
2307
+ /** When the record of a shared type was retired — it still resolves, but lists leave it out. */
2308
+ retiredAt?: string;
2327
2309
  [attrName: string]: unknown;
2328
2310
  }
2329
- /** The `content` page every list endpoint of the contract answers with. */
2330
- interface EntityDefinitionPage {
2331
- content?: EntityDefinition[];
2332
- }
2333
- /**
2334
- * A deprecated definition is not rendered. Which definitions the running application has at all is the release's
2335
- * business: it reads the released rows. (`DRAFT` is not rendered either, for an older backend that still answers it.)
2336
- */
2337
- declare function isRenderable(definition: EntityDefinition): boolean;
2338
2311
  /** `BaseConfiguration` key naming the org-scoped root of the base-entity endpoints. */
2339
2312
  export declare const ENTITY_SERVICE_ROOT_KEY = "ENTITY_SERVICE_ROOT";
2340
2313
  /**
@@ -2525,6 +2498,8 @@ export declare class DynamicEntityService extends BaseEntityRestService<DynamicE
2525
2498
  protected readonly filterParamName = "rsql";
2526
2499
  protected readonly sortParamName = "sort";
2527
2500
  constructor(entityDefinitionCode: string);
2501
+ /** Takes a retired record of a shared type back, so lists show it again. Only the common's own members may. */
2502
+ reinstate(id: string): Observable<unknown>;
2528
2503
  }
2529
2504
  /**
2530
2505
  * Facade of an entity whose payload lives inside another entity's document. Everything but the repository
@@ -2537,6 +2512,7 @@ export declare class DynamicEntityService extends BaseEntityRestService<DynamicE
2537
2512
  */
2538
2513
  export declare abstract class EmbeddedEntityFacade<Entity extends BaseEntity> extends BaseEntityFacade<Entity> {
2539
2514
  private _accessor?;
2515
+ private _directWriter?;
2540
2516
  /** Takes no mapper: an embedded row is carried, and mapped, by the containing entity's payload. */
2541
2517
  protected createService(): BaseEntityService<Entity>;
2542
2518
  /**
@@ -2553,6 +2529,7 @@ export declare abstract class EmbeddedEntityFacade<Entity extends BaseEntity> ex
2553
2529
  */
2554
2530
  protected createStoreClass(): Type<unknown>;
2555
2531
  private readonly rowKeyOf;
2532
+ private get directWriter();
2556
2533
  private get accessor();
2557
2534
  static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedEntityFacade<any>, never>;
2558
2535
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
@@ -2747,7 +2724,11 @@ interface EmbeddedChildRoute {
2747
2724
  * navigation. A child that names itself would otherwise be an infinite structure; lazily, it is finite at
2748
2725
  * any moment and Angular memoizes each level it has expanded.
2749
2726
  */
2750
- export declare function baseEntityRoutes(embeddedChildren?: EmbeddedChildRoute[], extraTabs?: EntityTabDescriptor[]): Routes;
2727
+ export declare function baseEntityRoutes(embeddedChildren?: EmbeddedChildRoute[], extraTabs?: EntityTabDescriptor[], contextObject?: ContextObjectRoutes): Routes;
2728
+ /** An entity that `canContextObject`: what its routes need to know to address the parts through the picked object. */
2729
+ interface ContextObjectRoutes {
2730
+ entityName: string;
2731
+ }
2751
2732
  /** The stand-alone entity routes, unchanged for every caller that has no embedded children to mount. */
2752
2733
  export declare const BASE_ENTITY_ROUTES: Routes;
2753
2734
  /** Everything needed to mount one entity's List and Details screens somewhere. */
@@ -2782,6 +2763,7 @@ export declare class EntityScreenResolver {
2782
2763
  private readonly injector;
2783
2764
  private readonly tabContributors;
2784
2765
  private readonly stateControl;
2766
+ private readonly calculatedControl;
2785
2767
  /** `undefined` when neither a facade nor a definition answers to `entityName`. */
2786
2768
  resolve(entityName: string | undefined): Promise<EntityScreens | undefined>;
2787
2769
  /**
@@ -2791,6 +2773,13 @@ export declare class EntityScreenResolver {
2791
2773
  * throws leaves the descriptor as it was — the attribute stays editable, as it was before base-state existed.
2792
2774
  */
2793
2775
  private markStateAttribute;
2776
+ /**
2777
+ * Turns the attributes a calculation writes into {@link FormControlType.CALCULATED} controls, so the form shows
2778
+ * them read-only and recomputed instead of offering a free edit that the backend would discard. Same contract as
2779
+ * {@link markStateAttribute}: idempotent, a provider that throws leaves the descriptor as it was, and an attribute
2780
+ * a state machine governs stays STATE.
2781
+ */
2782
+ private markCalculatedAttributes;
2794
2783
  /**
2795
2784
  * The descriptor's extra tabs after every contributor has been asked — and **written back onto the
2796
2785
  * descriptor**, because that is what `BaseEntityTabsComponent` renders the links from. The routes are
@@ -2881,6 +2870,25 @@ interface EntityStateControl {
2881
2870
  stateAttributeOf(descriptor: BaseEntityDescriptor): Promise<string | undefined> | string | undefined;
2882
2871
  }
2883
2872
  export declare const ENTITY_STATE_CONTROL: InjectionToken<EntityStateControl>;
2873
+ /**
2874
+ * What renders a {@link FormControlType.CALCULATED} attribute, and which attributes of an entity are one.
2875
+ *
2876
+ * base-entity knows that some attribute *holds* a derived value; it cannot know the calculation behind it —
2877
+ * that is base-calculation's, and base-entity does not depend on it. So the feature that owns the calculations
2878
+ * registers this, the way base-state registers {@link ENTITY_STATE_CONTROL}, and nothing on either side names
2879
+ * the other. Without a registration a CALCULATED attribute is shown read-only as a label.
2880
+ */
2881
+ interface EntityCalculatedControl {
2882
+ /** A `BaseFormControlComponent` subclass. Typed loosely: a stricter type would close an import cycle. */
2883
+ component: Type<unknown>;
2884
+ /**
2885
+ * The names of the attributes of `descriptor`'s objects that a calculation writes — usually none.
2886
+ * {@link EntityScreenResolver} asks this once per resolved entity and turns each into a CALCULATED control,
2887
+ * so an entity authored before the calculation existed needs no descriptor change.
2888
+ */
2889
+ calculatedAttributesOf(descriptor: BaseEntityDescriptor): Promise<string[]> | string[];
2890
+ }
2891
+ export declare const ENTITY_CALCULATED_CONTROL: InjectionToken<EntityCalculatedControl>;
2884
2892
  interface EntityScreenRouteOptions {
2885
2893
  /** Entity whose screens to mount, by descriptor name. */
2886
2894
  entityName: string | undefined;
@@ -2912,8 +2920,13 @@ interface EntityScreenRouteOptions {
2912
2920
  * every tab click and row link do nothing at all — see {@link entityScreenChildren}.
2913
2921
  */
2914
2922
  export declare function entityScreenRoute({ entityName, screens, hostPath, data }: EntityScreenRouteOptions): Route;
2915
- /** Route `data` key under which {@link entityScreenRoute} puts the descriptor to render. */
2923
+ /**
2924
+ * Route data keys of an entity's screens. Kept apart from the screens component, which pulls in the whole entity
2925
+ * container, so that the list can read them without importing the screens back.
2926
+ */
2916
2927
  export declare const ENTITY_DESCRIPTOR_ROUTE_DATA_KEY = "entityDescriptor";
2928
+ export declare const REQUESTED_ENTITY_ROUTE_DATA_KEY = "requestedEntityName";
2929
+ /** Route `data` key under which {@link entityScreenRoute} puts the descriptor to render. */
2917
2930
  /**
2918
2931
  * Route `data` key naming the entity the route *asked* for — which is all this component needs, and needs
2919
2932
  * even when nothing answered to it.
@@ -2922,7 +2935,6 @@ export declare const ENTITY_DESCRIPTOR_ROUTE_DATA_KEY = "entityDescriptor";
2922
2935
  * and everything that reads it — `readEmbeddedBreadcrumb`, `EntityRouteRegistry` — would take this route to
2923
2936
  * be that one. See the note in {@link entityScreenRoute}.
2924
2937
  */
2925
- export declare const REQUESTED_ENTITY_ROUTE_DATA_KEY = "requestedEntityName";
2926
2938
  /**
2927
2939
  * Hosts one entity's generated screens at a route: List and Details, with the tab bar, toolbar and status
2928
2940
  * bar `BaseEntityTabsComponent` brings, and the outlet its own child routes render in.
@@ -2953,6 +2965,12 @@ interface EmbeddedRouteLevel {
2953
2965
  entityName: string;
2954
2966
  /** `undefined` on a list route, {@link BaseUrlSegments.NewEntity} for a row being created. */
2955
2967
  entityId: string | undefined;
2968
+ /**
2969
+ * Set when this level is a **working context's** entity — `ctx/<name>/<id>` — rather than an entity's own route. It is
2970
+ * the root of the aggregate all the same: the rows below it are addressed through the URL exactly as below an entity's
2971
+ * details form, but saved through the item endpoints, as no form of the whole entity is open to save them.
2972
+ */
2973
+ workingContext?: string;
2956
2974
  }
2957
2975
  /** A {@link EmbeddedRouteLevel} with the two URLs the level can be navigated by. */
2958
2976
  interface EmbeddedBreadcrumbLevel extends EmbeddedRouteLevel {
@@ -2965,6 +2983,8 @@ interface EmbeddedBreadcrumbLevel extends EmbeddedRouteLevel {
2965
2983
  interface EmbeddedRouteContext {
2966
2984
  rootEntityName: string;
2967
2985
  rootId: string;
2986
+ /** The working context the aggregate's root is the entity of, when it is one. See {@link EmbeddedRouteLevel.workingContext}. */
2987
+ viaWorkingContext?: string;
2968
2988
  /** Hops from the root down to the **owner** of these rows; `[]` when the owner is the root itself. */
2969
2989
  path: EmbeddedPath;
2970
2990
  /** The owner's attribute carrying these rows. */
@@ -2972,59 +2992,6 @@ interface EmbeddedRouteContext {
2972
2992
  entityName: string;
2973
2993
  referenceIdField?: string;
2974
2994
  }
2975
- /**
2976
- * The chain of entities the URL walks through, outermost first — `Test Entity/1`, then
2977
- * `Embedded Component/embedded_1_1`, and so on. It reads the URL only, which is what makes a deep link and a
2978
- * page refresh resolve to the same row as a drill-down.
2979
- *
2980
- * The entity name sits on the container route and the id on its `:entityId/details` child, and the router
2981
- * hands both **down** to the routes nested below them. Three rules undo that inheritance:
2982
- *
2983
- * - a name counts only from the route that *declares* it in its config, not from every descendant that
2984
- * inherited it — see {@link declaredEntityName};
2985
- * - a name repeated while the level below it still has no id is that level's own details route echoing its
2986
- * container, not a new level — whereas a repeat *after* an id is a genuinely self-nesting child
2987
- * (`app-nav-item/a/details/app-nav-item/b/details`), which `App Nav Item` needs;
2988
- * - an id counts only from the route that actually declares `:entityId`, so a nested branch does not adopt
2989
- * the id of the entity it hangs under.
2990
- */
2991
- declare function readEmbeddedRouteChain(snapshot: ActivatedRouteSnapshot | null): EmbeddedRouteLevel[];
2992
- /**
2993
- * The same chain, each level carrying the URL of its own screen — which is what turns it into a
2994
- * breadcrumb the user can walk back up.
2995
- *
2996
- * The URL is accumulated from the segments of the routes the walk passes, so a level's `url` ends at the
2997
- * last route that belongs to *it*: `<owner>/<id>/details` for a level a row is named on. `baseUrl` stops
2998
- * one step earlier, before the level's own entity segment, and is what a sibling list or details URL is
2999
- * built on.
3000
- */
3001
- declare function readEmbeddedBreadcrumb(snapshot: ActivatedRouteSnapshot | null): EmbeddedBreadcrumbLevel[];
3002
- /**
3003
- * The part of a URL chain that is **one aggregate**: the longest tail in which every level is an embedded
3004
- * component of the level above it.
3005
- *
3006
- * A URL may walk through entities that have nothing to do with each other. The designer's Preview tab is the
3007
- * case that forced this: a previewed application's screens are mounted *below* `app-definition/<id>`, so an
3008
- * order line's chain reads `App Definition` -> `Order` -> `Order Line`. Taking the outermost level as the
3009
- * aggregate root then asks `App Definition` for an embedded `Order` it has never heard of, and nothing
3010
- * resolves — which showed up as every embedded list in a previewed application coming up empty, and every
3011
- * link into an embedded row bouncing back to the form it was clicked on.
3012
- *
3013
- * Walking back from the deepest level and stopping at the first pair that is not a containment expresses
3014
- * "one aggregate" without needing to know *why* the outer levels are there. For an ordinary authoring URL,
3015
- * where the whole chain is one aggregate, it stops at the root and changes nothing.
3016
- */
3017
- declare function aggregateChainOf<Level extends EmbeddedRouteLevel>(levels: readonly Level[], descriptorOf: (entityName: string) => BaseEntityDescriptor | undefined): Level[];
3018
- /**
3019
- * Turns the URL chain into a path into the root's payload. Resolving the hops needs the payload itself,
3020
- * because a row's position is what addresses it — the URL carries the row's *key*, and only the aggregate
3021
- * knows where that key currently sits.
3022
- *
3023
- * Returns `undefined` when the chain names no embedded level, when a descriptor is missing, or when an
3024
- * intermediate row cannot be found — a stale deep link, which the caller turns into a redirect rather than
3025
- * into a form bound to the wrong row.
3026
- */
3027
- declare function resolveEmbeddedRouteContext(levels: readonly EmbeddedRouteLevel[], rootPayload: unknown, descriptorOf: (entityName: string) => BaseEntityDescriptor | undefined): EmbeddedRouteContext | undefined;
3028
2995
  /** An embedded level resolved against the live aggregate: where its rows are, and who owns the document. */
3029
2996
  interface ResolvedEmbeddedAggregate {
3030
2997
  context: EmbeddedRouteContext;
@@ -3073,6 +3040,83 @@ export declare class EmbeddedAggregateAccessor {
3073
3040
  static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedAggregateAccessor, never>;
3074
3041
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
3075
3042
  }
3043
+ /**
3044
+ * One item of an embedded collection. Free-form, as the entity's payload is. `id` identifies it, and `itemVersion` counts
3045
+ * the changes made through the item endpoints — the server keeps both, so neither is sent back as a change.
3046
+ */
3047
+ type CollectionItem = Record<string, unknown>;
3048
+ /** What a read answers: the items, and the version of the object they were read from. */
3049
+ interface CollectionRead {
3050
+ items: CollectionItem[];
3051
+ /** `undefined` when the server sent no `ETag`. */
3052
+ version: string | undefined;
3053
+ }
3054
+ /**
3055
+ * Reads and changes **one item** of an embedded collection of an entity instance — `entities/<type>/<id>/<attr>[/<itemId>]`
3056
+ * — so that adding a zone to a warehouse sends the zone, not the warehouse.
3057
+ *
3058
+ * The object's version travels as an `ETag`: every answer carries it, and a change that names it back as `If-Match` is
3059
+ * refused with a 409 when someone else saved in between. A change that names none applies to whatever is stored.
3060
+ */
3061
+ export declare class EmbeddedCollectionService {
3062
+ private readonly http;
3063
+ private readonly definitions;
3064
+ private readonly root;
3065
+ list(entityName: string, id: string, attrName: string): Promise<CollectionRead>;
3066
+ /** The item as stored — with the `id` the server assigned. */
3067
+ append(entityName: string, id: string, attrName: string, item: CollectionItem): Promise<CollectionItem>;
3068
+ /**
3069
+ * A merge patch: members present replace the stored ones, a `null` member is removed. `version` is the item's own version
3070
+ * as last read; the server refuses the change with a 409 when the item has changed since.
3071
+ */
3072
+ patch(entityName: string, id: string, attrName: string, itemId: string, patch: CollectionItem, version?: string): Promise<CollectionItem>;
3073
+ remove(entityName: string, id: string, attrName: string, itemId: string, version?: string): Promise<void>;
3074
+ /**
3075
+ * A collection nested in an item of another: the `childAttrName` collection of the item `itemId` of `attrName`. The same
3076
+ * operations as above, one level down.
3077
+ */
3078
+ listNested(entityName: string, id: string, attrName: string, itemId: string, childAttrName: string): Promise<CollectionRead>;
3079
+ appendNested(entityName: string, id: string, attrName: string, itemId: string, childAttrName: string, item: CollectionItem): Promise<CollectionItem>;
3080
+ patchNested(entityName: string, id: string, attrName: string, itemId: string, childAttrName: string, childItemId: string, patch: CollectionItem, version?: string): Promise<CollectionItem>;
3081
+ removeNested(entityName: string, id: string, attrName: string, itemId: string, childAttrName: string, childItemId: string, version?: string): Promise<void>;
3082
+ /** The URL of the collection or item at the given path: `attrName`, then alternately an item id and an attribute. */
3083
+ private url;
3084
+ static ɵfac: i0.ɵɵFactoryDeclaration<EmbeddedCollectionService, never>;
3085
+ static ɵprov: i0.ɵɵInjectableDeclaration<any>;
3086
+ }
3087
+ /**
3088
+ * The merge patch that turns `before` into `after`: the members that changed, and `null` for those that were removed.
3089
+ * An unchanged item makes an empty patch, which the caller can skip.
3090
+ */
3091
+ export declare function mergePatch(before: CollectionItem, after: CollectionItem): CollectionItem;
3092
+ /**
3093
+ * Saves an embedded row **straight through the item endpoints**, for an aggregate whose root is a working context.
3094
+ *
3095
+ * An entity's own form stages a row in the whole document and the form's Save persists it. A working context has no form
3096
+ * of the whole entity — that is the point of it — so there is nothing to Save: each row goes to the server as the row, under
3097
+ * its own version, and the root is read again so every screen shows what is stored.
3098
+ *
3099
+ * The backend addresses a collection one level below the entity's own, and the row inside it, by `id`. A row nested deeper
3100
+ * has no endpoint yet, and a row stored before ids existed has none to address it by; both say so rather than guess.
3101
+ */
3102
+ declare class DirectEmbeddedWriter {
3103
+ private readonly collections;
3104
+ /** Whether this aggregate is saved here rather than staged in the root document. */
3105
+ handles(resolved: ResolvedEmbeddedAggregate): boolean;
3106
+ /** The row as stored: with the `id` and `itemVersion` the server assigned. */
3107
+ append(resolved: ResolvedEmbeddedAggregate, row: EmbeddedRow): Promise<CollectionItem>;
3108
+ /** Sends only what changed, against the row's own version; the row unchanged when nothing did. */
3109
+ patch(resolved: ResolvedEmbeddedAggregate, before: EmbeddedRow, after: EmbeddedRow): Promise<CollectionItem>;
3110
+ remove(resolved: ResolvedEmbeddedAggregate, before: EmbeddedRow): Promise<void>;
3111
+ private target;
3112
+ /** The row the collection is nested in, when it is: its attribute at the top, and its `id`. */
3113
+ private ownerOf;
3114
+ private itemIdOf;
3115
+ /** Reads the root again, so the rows every screen lists are the stored ones. */
3116
+ private refresh;
3117
+ static ɵfac: i0.ɵɵFactoryDeclaration<DirectEmbeddedWriter, never>;
3118
+ static ɵprov: i0.ɵɵInjectableDeclaration<any>;
3119
+ }
3076
3120
  /**
3077
3121
  * The repository of an **embedded** entity: one that has no endpoint of its own because its payload travels
3078
3122
  * inside its parent's document.
@@ -3089,7 +3133,11 @@ export declare class EmbeddedAggregateAccessor {
3089
3133
  export declare class EmbeddedEntityService<Entity extends BaseEntity> implements BaseEntityService<Entity> {
3090
3134
  private readonly entityName;
3091
3135
  private readonly accessor;
3092
- constructor(entityName: string, accessor: EmbeddedAggregateAccessor);
3136
+ /** Saves a row on its own where the aggregate's root is a working context; absent, every write is staged. */
3137
+ private readonly direct?;
3138
+ constructor(entityName: string, accessor: EmbeddedAggregateAccessor,
3139
+ /** Saves a row on its own where the aggregate's root is a working context; absent, every write is staged. */
3140
+ direct?: DirectEmbeddedWriter | undefined);
3093
3141
  /**
3094
3142
  * The row arrives with its key already set — `createEntity()` mints one for an `id`-bearing child, and a
3095
3143
  * child keyed by something else (`App Region` by `type`) gets it from the form — so there is no
@@ -3197,7 +3245,10 @@ interface NavigationState {
3197
3245
  responsePayloads: Map<string, NavigationPayload>;
3198
3246
  requestPayloads: Map<string, NavigationPayload>;
3199
3247
  returnTo: string;
3200
- formSnapshot: Record<string, unknown> | undefined;
3248
+ /** The values each form left for a round trip, keyed by the entity of the form that left them: each takes its own. */
3249
+ formSnapshots: Record<string, Record<string, unknown>>;
3250
+ /** Set when a picker sends the user to a list to choose from, until the router navigates on its own. */
3251
+ roundTripOpen: boolean;
3201
3252
  }
3202
3253
  export declare function snakeCaseName(entityName: string): string;
3203
3254
  export declare const BaseFormNavigatorSingletonStore: import("@angular/core").Type<{
@@ -3211,8 +3262,8 @@ export declare const BaseFormNavigatorSingletonStore: import("@angular/core").Ty
3211
3262
  responsePayloads: import("@angular/core").Signal<Map<string, NavigationPayload>>;
3212
3263
  requestPayloads: import("@angular/core").Signal<Map<string, NavigationPayload>>;
3213
3264
  returnTo: import("@angular/core").Signal<string>;
3214
- formSnapshot: import("@angular/core").Signal<Record<string, unknown> | undefined>;
3215
- captureFormSnapshot: (snapshot: Record<string, unknown>) => void;
3265
+ formSnapshots: import("@angular/core").Signal<Record<string, Record<string, unknown>>>;
3266
+ roundTripOpen: import("@angular/core").Signal<boolean>;
3216
3267
  determineCurrentUrl: () => string;
3217
3268
  determineOwnerUrl: () => string;
3218
3269
  determineActiveRouteSegment: () => void;
@@ -3229,7 +3280,10 @@ export declare const BaseFormNavigatorSingletonStore: import("@angular/core").Ty
3229
3280
  showsScreenOf: (entityName: string) => boolean;
3230
3281
  destroyNavigationTracking: () => void;
3231
3282
  initializeNavigationTracking: () => void;
3232
- popFormSnapshot: () => Record<string, unknown> | undefined;
3283
+ beginRoundTrip: () => void;
3284
+ hasRoundTrip: () => boolean;
3285
+ keepFormSnapshot: (owner: string, values: Record<string, unknown>) => void;
3286
+ popFormSnapshot: (owner: string) => Record<string, unknown> | undefined;
3233
3287
  popRequestPayload: (attrName?: string) => NavigationPayload | undefined;
3234
3288
  popResponsePayload: (attrName?: string) => NavigationPayload | undefined;
3235
3289
  pushResponsePayload: (payload: NavigationPayload) => void;
@@ -3245,7 +3299,8 @@ export declare const BaseFormNavigatorSingletonStore: import("@angular/core").Ty
3245
3299
  responsePayloads: Map<string, NavigationPayload>;
3246
3300
  requestPayloads: Map<string, NavigationPayload>;
3247
3301
  returnTo: string;
3248
- formSnapshot: Record<string, unknown> | undefined;
3302
+ formSnapshots: Record<string, Record<string, unknown>>;
3303
+ roundTripOpen: boolean;
3249
3304
  }>>;
3250
3305
  export declare function BaseFormNavigatorStore(entityName: string): import("@ngrx/signals").SignalStoreFeature<import("@ngrx/signals").EmptyFeatureResult, {
3251
3306
  state: {};
@@ -3297,122 +3352,6 @@ export declare class EntityRouteRegistry {
3297
3352
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
3298
3353
  }
3299
3354
  export declare function provideEntityRouteRegistry(): EnvironmentProviders;
3300
- /**
3301
- * Talks to Firestore straight from the browser, bypassing the OpenAPI contract entirely.
3302
- *
3303
- * @deprecated Use `BaseEntityRestService` against the contract. This adapter is kept for consumers
3304
- * who deploy on Firestore; ProcessPuzzle itself no longer does, so it is no longer exercised by any
3305
- * environment here.
3306
- *
3307
- * Why this path is being retired rather than kept as an option:
3308
- * - **It is a second seam.** With an adapter chosen in the client, every feature has to be built
3309
- * twice, and only the REST half is covered by a contract test. Drift on this side is undetectable
3310
- * until it reaches a user.
3311
- * - **Its paging is a fiction.** `findByQueryAsync` reports `totalPages: 1` and
3312
- * `totalElements: content.length`, so a paginator tells the truth on REST and guesses here.
3313
- * - **Firestore cannot answer the query language.** `createQuery` maps a
3314
- * {@link BaseEntityQueryCondition} onto Firestore constraints, which have no substring or
3315
- * case-insensitive compare, and silently drop documents that lack the `orderBy` field.
3316
- * - **Authorization ends up in two dialects** — `firestore.rules` here, server-side policy there —
3317
- * so tenant isolation has to be got right twice.
3318
- *
3319
- * Nothing about it is broken today and no removal date is set, but only one call site is left to
3320
- * migrate before it can go: `BaseEntityFacade.createService` still returns it when
3321
- * `BACKEND_SERVICE_PROVIDER` is not `rest`. `ApplicationPropertyService` in `base-widget` no longer
3322
- * extends it, and the testbed's own Firestore sample is gone — its entities are served through the
3323
- * contract like every other deployment's.
3324
- *
3325
- * Both of its dependencies on `@angular/fire` are injected rather than imported: the instance as
3326
- * {@link FIRESTORE} rather than the `Firestore` class, and the module functions as {@link FIRESTORE_API}.
3327
- * Each token's own file says which testability problem it solves.
3328
- */
3329
- export declare class BaseEntityFirestoreService<Entity extends BaseEntity> implements BaseEntityService<Entity> {
3330
- protected entityMapper: BaseEntityMapper<Entity>;
3331
- protected collectionName: string;
3332
- protected collection: import("@firebase/firestore").CollectionReference<DocumentData, DocumentData>;
3333
- protected readonly firestore: import("@angular/fire/firestore").Firestore;
3334
- protected readonly firestoreApi: import("@processpuzzle/base-entity").FirestoreApi;
3335
- constructor(entityMapper: BaseEntityMapper<Entity>, collectionName: string);
3336
- add(entity: Entity): Observable<PersistedEntity<Entity>>;
3337
- delete(id: string): Observable<unknown>;
3338
- deleteAll(): Observable<unknown>;
3339
- findAll(page?: number, pageSize?: number): Observable<BaseEntityLoadResponse<PersistedEntity<Entity>> | PersistedEntity<Entity>[]>;
3340
- findById(id: string): Observable<PersistedEntity<Entity> | void>;
3341
- findByQuery(queryCondition: BaseEntityQueryCondition): Observable<BaseEntityLoadResponse<PersistedEntity<Entity>> | PersistedEntity<Entity>[]>;
3342
- update(entity: PersistedEntity<Entity>): Observable<PersistedEntity<Entity>>;
3343
- protected addAsync(entity: Entity): Promise<PersistedEntity<Entity>>;
3344
- protected createQuery(queryCondition: BaseEntityQueryCondition): import("@firebase/firestore").Query<DocumentData, DocumentData>;
3345
- protected findByQueryAsync(queryCondition: BaseEntityQueryCondition): Promise<BaseEntityLoadResponse<PersistedEntity<Entity>> | PersistedEntity<Entity>[]>;
3346
- protected mapCollection(source: Observable<unknown[]>): PersistedEntity<Entity>[];
3347
- protected mapDocument(docData: unknown): PersistedEntity<Entity>;
3348
- private mapEntity;
3349
- private updateAsync;
3350
- }
3351
- /**
3352
- * The Firestore instance {@link BaseEntityFirestoreService} reads and writes through.
3353
- *
3354
- * The service used to inject `@angular/fire`'s `Firestore` class directly. Angular matches providers by
3355
- * object identity, and a bare specifier does not always resolve to one object: mock the barrel, or let a
3356
- * build inline it on one side of the graph and import it on the other, and the module the service imports
3357
- * is a second instance of the same file. The class is then two distinct tokens — one registered, the other
3358
- * asked for — and DI fails with `NG0201: No provider found for Firestore`.
3359
- *
3360
- * An `InjectionToken` declared here is a single object owned by this library. Note the `import type`: it
3361
- * carries no runtime dependency on `@angular/fire/firestore`, which is what keeps this module out of the
3362
- * blast radius when a test replaces the barrel, and so keeps the token one object.
3363
- *
3364
- * Applications that deploy on Firestore bind it with `provideFirestoreToken()`, next to their existing
3365
- * `provideFirestore(...)` call.
3366
- */
3367
- export declare const FIRESTORE: InjectionToken<Firestore>;
3368
- /**
3369
- * The subset of the Firestore module API that {@link BaseEntityFirestoreService} calls.
3370
- */
3371
- interface FirestoreApi {
3372
- readonly collection: typeof collection;
3373
- readonly deleteDoc: typeof deleteDoc;
3374
- readonly doc: typeof doc;
3375
- readonly getDoc: typeof getDoc;
3376
- readonly getDocs: typeof getDocs;
3377
- readonly limit: typeof limit;
3378
- readonly orderBy: typeof orderBy;
3379
- readonly query: typeof query;
3380
- readonly setDoc: typeof setDoc;
3381
- readonly updateDoc: typeof updateDoc;
3382
- readonly where: typeof where;
3383
- }
3384
- /**
3385
- * Firestore's free functions, reached through DI instead of imported at each call site.
3386
- *
3387
- * This exists so the adapter can be tested deterministically, and the indirection is the only way to get
3388
- * that here. The suite used to `vi.mock('@angular/fire/firestore')` and assert on the mocked functions.
3389
- * That is a bare specifier, which the Angular unit-test system does allow — but whether the replacement
3390
- * reaches *this library's* modules is not stable: the builder may inline the barrel into the source bundle,
3391
- * where a mock cannot touch it. The suite consequently passed or failed at roughly even odds on an
3392
- * unchanged commit — surfacing either as the real `collection()` rejecting a plain object, or, since the
3393
- * real `Firestore` class then became the token the service asked for, as
3394
- * `NG0201: No provider found for Firestore`. CI failed on the coin flip.
3395
- *
3396
- * Nor can the barrel be hidden behind a relative re-export and that mocked instead: the runner rejects it
3397
- * outright — *"vi.mock and related methods are not supported for relative imports with the Angular
3398
- * unit-test system. Please use Angular TestBed for mocking dependencies."* This token is that advice taken.
3399
- *
3400
- * The default factory returns the real functions, so an application binds nothing.
3401
- */
3402
- export declare const FIRESTORE_API: InjectionToken<FirestoreApi>;
3403
- /**
3404
- * Binds {@link FIRESTORE} to the instance `provideFirestore(...)` registered, for an application that
3405
- * deploys `BaseEntityFirestoreService` against a real Firestore.
3406
- *
3407
- * One line next to the `provideFirestore(...)` call:
3408
- * ```ts
3409
- * providers: [provideFirebaseApp(() => initializeApp(config)), provideFirestore(() => getFirestore()), provideFirestoreToken()]
3410
- * ```
3411
- *
3412
- * It lives in its own file on purpose. `firestore.token.ts` must not import `@angular/fire/firestore` at
3413
- * run-time — see the note there — and this is where the one import that has to exist is confined.
3414
- */
3415
- export declare function provideFirestoreToken(): Provider;
3416
3355
  export declare enum FlexDirection {
3417
3356
  CONTAINER = 0,
3418
3357
  COLUMN = 1,
@@ -3485,6 +3424,21 @@ interface LookupTable extends BaseEntity {
3485
3424
  value: string | number;
3486
3425
  description?: string;
3487
3426
  }
3427
+ /**
3428
+ * Knows which of the open entity forms hold edits that have not been saved.
3429
+ *
3430
+ * An embedded child's form and its owner's stay alive together, and the owner is what has to be saved even when
3431
+ * the edit was made in the child — so the status bar asks here rather than any one form.
3432
+ */
3433
+ export declare class UnsavedChangesRegistry {
3434
+ private readonly sources;
3435
+ /** True while any registered form has unsaved changes. */
3436
+ readonly hasUnsavedChanges: Signal<boolean>;
3437
+ /** Registers a form's own "has unsaved changes" signal; the returned function unregisters it. */
3438
+ register(source: Signal<boolean>): () => void;
3439
+ static ɵfac: i0.ɵɵFactoryDeclaration<UnsavedChangesRegistry, never>;
3440
+ static ɵprov: i0.ɵɵInjectableDeclaration<any>;
3441
+ }
3488
3442
  /**
3489
3443
  * Defines a single column in the exported PDF table.
3490
3444
  * Maps directly from your entity descriptor's field definitions.
@@ -3758,6 +3712,10 @@ interface EntityDefinitionDto {
3758
3712
  releaseState?: ReleaseState;
3759
3713
  componentParents?: string[];
3760
3714
  isEmbedded?: boolean;
3715
+ canContextObject?: boolean;
3716
+ sharing?: EntitySharing;
3717
+ identifiers?: string[][];
3718
+ sharedFrom?: string;
3761
3719
  attributes?: EntityAttributeDto[];
3762
3720
  version?: number;
3763
3721
  createdAt?: string;
@@ -3850,6 +3808,7 @@ export declare const EntityDefinitionStore: import("@angular/core").Type<{
3850
3808
  createEntity: () => EntityDefinition;
3851
3809
  add: (entity: EntityDefinition) => Promise<import("@processpuzzle/base-entity").PersistedEntity<EntityDefinition> | undefined>;
3852
3810
  delete: (id: string) => Promise<void>;
3811
+ keyOf: EntityKeyResolver<EntityDefinition>;
3853
3812
  hasStagedChanges: (id: string) => boolean;
3854
3813
  deleteAll: import("@ngrx/signals/rxjs-interop").RxMethod<void>;
3855
3814
  deselectAll: () => void;
@@ -3947,5 +3906,439 @@ export declare class EntityDefinitionContainerComponent implements OnDestroy {
3947
3906
  static ɵfac: i0.ɵɵFactoryDeclaration<EntityDefinitionContainerComponent, never>;
3948
3907
  static ɵcmp: i0.ɵɵComponentDeclaration<EntityDefinitionContainerComponent, "pp-entity-definition-container", never, {}, {}, never, never, true, never>;
3949
3908
  }
3950
- export type { AddressFormat, ArtifactAttr, BaseEntity, BaseEntityDescriptorOptions, BaseEntityFacadeRegistry, BaseEntityFormBuilder, BaseEntityLoadResponse, BaseEntityMapper, BaseEntityQueryCondition, DateFormat, DateStyle, DefinitionLookup, DynamicEntity, EmbeddedBreadcrumbLevel, EmbeddedChildRoute, EmbeddedPath, EmbeddedPathStep, EmbeddedRouteContext, EmbeddedRouteLevel, EmbeddedRow, EntityComment, EntityDefinitionStatus, EntityOptions, EntityScreenRouteOptions, EntityScreens, EntityServiceKind, EntityStateControl, EntityTabContributor, EntityTabDescriptor, EntityValueKind, EvaluatableRule, FilterCondition, FirestoreApi, GeoLocation, GeoLocatorError, GeoPoint, LocationSource, LookupTable, MapProvider, Multiplicity, MultiplicityHolder, NavigationPayload, NavigationState, ObjectUriResponse, OrderByCondition, PdfColumnDefinition, PdfExportDialogResult, PdfExportOptions, PdfExportResult, PersistedBaseEntity, PersistedEntity, PostalAddress, ResolvedDynamicEntity, ResolvedEmbeddedAggregate, RichTextContent, RuleEngine, RuleEvaluationResult, RuleSeverity, Selectable, SelectablesInput, TimeStyle };
3909
+ /** One transition the entity can take from its current state, as a button or a menu entry shows it. */
3910
+ interface EntityStateTransition {
3911
+ /** The trigger that fires it — what a route's or widget's `triggers` list names. */
3912
+ key: string;
3913
+ /** The transition's own name when the machine gives it one, the trigger otherwise. */
3914
+ label: string;
3915
+ /** False while a guard refuses it; {@link blockedReason} may say why. */
3916
+ enabled: boolean;
3917
+ blockedReason?: string;
3918
+ }
3919
+ /** What is known of an entity's state: where it is, and where it can go. */
3920
+ interface EntityStateSnapshot {
3921
+ /** The attribute of the entity that holds the state, as the machine names it. */
3922
+ stateAttribute?: string;
3923
+ currentKey: string;
3924
+ /** The current state's name, which is what a badge shows. */
3925
+ currentLabel: string;
3926
+ transitions: EntityStateTransition[];
3927
+ }
3928
+ interface EntityStateFireResult {
3929
+ success: boolean;
3930
+ /** Already translated, for the user: the new state, or why the transition was refused. */
3931
+ message: string;
3932
+ }
3933
+ /**
3934
+ * The state machine operations a working context needs, supplied by the state feature (`provideEntityStateControl`
3935
+ * in base-state-frontend) rather than called from here, so base-entity does not depend on it. Without a provider
3936
+ * a context simply has no state to show and no transitions to offer.
3937
+ */
3938
+ interface EntityStateActions {
3939
+ /** `undefined` for an entity no state machine governs. */
3940
+ stateOf(entityName: string, id: string): Promise<EntityStateSnapshot | undefined>;
3941
+ fire(entityName: string, id: string, triggerKey: string, version: number): Promise<EntityStateFireResult>;
3942
+ }
3943
+ export declare const ENTITY_STATE_ACTIONS: InjectionToken<EntityStateActions>;
3944
+ /** A context the URL currently names, with what is known about its entity. */
3945
+ interface ActiveWorkingContext {
3946
+ name: string;
3947
+ id: string;
3948
+ definition: WorkingContextDefinition;
3949
+ descriptor: BaseEntityDescriptor | undefined;
3950
+ /** The entity as its store holds it now — so an edit saved in its form shows at once. `undefined` while loading. */
3951
+ entity: Record<string, unknown> | undefined;
3952
+ /** The URL of the context's root, `…/ctx/<name>/<id>`. */
3953
+ url: string;
3954
+ }
3955
+ /**
3956
+ * Holds the active working contexts. **The URL is the source of truth**: what this service reports is read off
3957
+ * the current route (`ctx/<name>/<id>/...`), so a refresh, a deep link and a second device need nothing extra.
3958
+ * localStorage keeps the last id per context, as the fallback a context view opened without one restores, and the
3959
+ * recently active ids the picker offers.
3960
+ *
3961
+ * Selecting and clearing are navigations: they change the URL, and the route guards and this service follow it.
3962
+ */
3963
+ export declare class WorkingContextService {
3964
+ private readonly router;
3965
+ private readonly dialog;
3966
+ private readonly descriptorRegistry;
3967
+ private readonly declared;
3968
+ private readonly registered;
3969
+ private readonly levels;
3970
+ private readonly stateActions;
3971
+ private readonly snackBar;
3972
+ /** What is known of each active entity's state, by `<entity>/<id>`, with the entity version it was read at. */
3973
+ private readonly snapshots;
3974
+ private readonly snapshotsLoading;
3975
+ private readonly entityRoutes;
3976
+ /** Where the user was heading when no context object was known, by context name — see {@link rememberTarget}. */
3977
+ private readonly pendingTargets;
3978
+ /** Bumped whenever the remembered ids change, so {@link lastId} can be read reactively. */
3979
+ private readonly rememberedVersion;
3980
+ /** True while a transition is being fired, so a second click does not fire another. */
3981
+ readonly firing: import("@angular/core").WritableSignal<boolean>;
3982
+ /**
3983
+ * True while an application shell shows the contexts in a status bar of its own. The status bar inside the
3984
+ * entity tabs then leaves them out rather than showing them a second time.
3985
+ */
3986
+ readonly statusbarHostedByShell: import("@angular/core").WritableSignal<boolean>;
3987
+ /** Every declared context. A later registration of a name replaces an earlier one. */
3988
+ readonly definitions: Signal<WorkingContextDefinition[]>;
3989
+ /** The contexts the URL names an entity for, outermost first. */
3990
+ readonly active: Signal<ActiveWorkingContext[]>;
3991
+ constructor();
3992
+ /** Adds contexts declared at run-time — by an application definition loaded after bootstrap. Returns the undo. */
3993
+ register(definitions: WorkingContextDefinition[]): () => void;
3994
+ /**
3995
+ * The context of an entity that `canContextObject`: named like its URL segment, and addressed by its own URL
3996
+ * (`<aggregate>/<id>/<embedded>/list`) rather than a `ctx` segment. Created on first ask and then kept.
3997
+ */
3998
+ ensureAggregate(entityName: string): WorkingContextDefinition;
3999
+ /** Remembers the URL a user asked for while no context object was known; {@link takeTarget} hands it back once one is chosen. */
4000
+ rememberTarget(name: string, url: string): void;
4001
+ /** The URL waiting for a context object, without consuming it — the list says where the user is headed. */
4002
+ pendingTarget(name: string): string | undefined;
4003
+ private takeTarget;
4004
+ definitionOf(name: string): WorkingContextDefinition | undefined;
4005
+ /** The contexts an entity type is the root of — what decides whether its list offers "Set as active". */
4006
+ definitionsForEntity(entityName: string): WorkingContextDefinition[];
4007
+ current(name: string): ActiveWorkingContext | undefined;
4008
+ /** The entity behind an id, from its store or — when the store does not hold it yet — loaded into it. */
4009
+ load(name: string, id: string): Promise<Record<string, unknown> | undefined>;
4010
+ /**
4011
+ * Makes `id` the active entity of the context, by navigating to it. Inside the context the user stays on the
4012
+ * view they are on; from outside it they land on the context's first view. Selecting a parent drops its child
4013
+ * contexts from the URL, because their entities belong to the parent being left.
4014
+ *
4015
+ * Resolves `false` when the user declined the switch, or when the context cannot be addressed from here — a
4016
+ * child context while its parent is not active.
4017
+ */
4018
+ select(name: string, id: string): Promise<boolean>;
4019
+ /** Leaves the context: the view stays, showing its empty state. The stored fallback is dropped with it. */
4020
+ clear(name: string): Promise<boolean>;
4021
+ /** Whether leaving the active entity of the context should be confirmed first — see `confirmSwitchWhen`. */
4022
+ needsConfirmation(context: ActiveWorkingContext): boolean;
4023
+ /** The active entity's state and the transitions it can take; `undefined` until known, or when no state machine governs it. */
4024
+ stateOf(name: string): EntityStateSnapshot | undefined;
4025
+ /** The attribute holding the entity's state, as its state machine names it — what `state` in a declaration means. */
4026
+ stateAttributeOf(context: ActiveWorkingContext): string | undefined;
4027
+ /**
4028
+ * Fires a transition of the active entity of the context, tells the user what came of it and reloads the entity —
4029
+ * which refreshes the badge and the transitions on offer, since both follow the entity's version.
4030
+ * Resolves `true` when the transition ran.
4031
+ */
4032
+ fire(name: string, triggerKey: string): Promise<boolean>;
4033
+ /** The ids of the context's recently active entities, most recent first. */
4034
+ recent(name: string): string[];
4035
+ /** The id a context view opened without a context restores, when the context persists to localStorage. */
4036
+ lastId(name: string): string | undefined;
4037
+ remember(name: string, id: string): void;
4038
+ /** Drops an id that no longer resolves, so neither the fallback nor the picker offers it again. */
4039
+ forget(name: string, id: string): void;
4040
+ private stateKey;
4041
+ private loadState;
4042
+ private readUrl;
4043
+ private storeOf;
4044
+ private urlFor;
4045
+ /**
4046
+ * Where choosing `id` leads: back to the URL the user was refused at while none was known; otherwise the view they are on,
4047
+ * for another object; otherwise `null` — nowhere, the choice is only remembered.
4048
+ */
4049
+ private aggregateUrlFor;
4050
+ /** The first segment of the view inside a context — not a nested `ctx`, which belongs to the entity being left. */
4051
+ private viewOf;
4052
+ private confirmLeaving;
4053
+ private forgetLast;
4054
+ private readList;
4055
+ /** localStorage, or nothing where there is none (server rendering) or it is blocked. */
4056
+ private storage;
4057
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextService, never>;
4058
+ static ɵprov: i0.ɵɵInjectableDeclaration<any>;
4059
+ }
4060
+ /** What a working context's entity is made of, for the routes that open its embedded rows. */
4061
+ interface WorkingContextAggregate {
4062
+ /** The context's entity type. With it, the context's route is the root of the URL chain its embedded screens read. */
4063
+ entityName?: string;
4064
+ /** The embedded children of that entity, as the entity's own details route mounts them; derived from its descriptor. */
4065
+ embeddedChildren?: EmbeddedChildRoute[];
4066
+ }
4067
+ /**
4068
+ * The routes of `routes` bound to the context `contextName`, mounted twice:
4069
+ *
4070
+ * - `ctx/<name>/:contextId/<route>` resolves the active entity, through {@link workingContextGuard}. A bare
4071
+ * `ctx/<name>/<id>` lands on the first route.
4072
+ * - `ctx/<name>/<route>` is the same view **without** a context. It renders the "Select a …" empty state with
4073
+ * the picker embedded instead of the view — it never redirects to a list — and restores the last active
4074
+ * entity first when the context persists to localStorage.
4075
+ *
4076
+ * The id branch refuses an id that equals the first segment of one of the views, which is what keeps
4077
+ * `ctx/warehouse/zones` the empty state rather than a warehouse called `zones`.
4078
+ *
4079
+ * Nest a child context by calling this again inside `routes`; its URL then reads
4080
+ * `ctx/site/<id>/ctx/warehouse/<id>/...`.
4081
+ */
4082
+ export declare function workingContextRoutes(contextName: string, routes: Routes, aggregate?: WorkingContextAggregate): Routes;
4083
+ /**
4084
+ * Makes the entity named in the URL the active one. An id the entity's store cannot load is not an error page:
4085
+ * the same view is shown without a context, so the user can pick another.
4086
+ */
4087
+ export declare const workingContextGuard: CanActivateFn;
4088
+ /** A context view opened without a context continues with the last active entity, when the context persists it. */
4089
+ export declare const restoreWorkingContextGuard: CanActivateFn;
4090
+ /** The URL segment every context route starts with: `ctx/<name>/<id>/...`. */
4091
+ export declare const WORKING_CONTEXT_SEGMENT = "ctx";
4092
+ /** Route data naming the context a route belongs to. Read from the route's own config, never inherited. */
4093
+ export declare const WORKING_CONTEXT_ROUTE_DATA_KEY = "workingContext";
4094
+ export declare const WORKING_CONTEXT_ID_PARAM = "contextId";
4095
+ /** One context the URL walks through. `id` is undefined on the empty-state branch — a context view opened without one. */
4096
+ interface WorkingContextRouteLevel {
4097
+ name: string;
4098
+ /** True for a context object: the id segment of an aggregate's own URL, not an application's `ctx/<name>/<id>`. */
4099
+ aggregate: boolean;
4100
+ id: string | undefined;
4101
+ /** The URL up to and including this level's `ctx/<name>[/<id>]` segments. */
4102
+ url: string;
4103
+ /** The URL before this level's `ctx` segment, which a sibling context URL is built on. */
4104
+ baseUrl: string;
4105
+ /** What follows this level in the current URL — the view inside the context, with a leading `/`, or `''`. */
4106
+ rest: string;
4107
+ }
4108
+ /**
4109
+ * The contexts the URL walks through, outermost first. Read from the route configs the snapshot passes, so a
4110
+ * refresh and a deep link describe the same contexts as a selection does.
4111
+ */
4112
+ export declare function readWorkingContextLevels(snapshot: ActivatedRouteSnapshot | null): WorkingContextRouteLevel[];
4113
+ interface PickerRow {
4114
+ id: string;
4115
+ label: string;
4116
+ isActive: boolean;
4117
+ }
4118
+ /**
4119
+ * Picks the entity of a working context: a search over the context's `picker.searchFields` with the recently
4120
+ * active entities on top. Used inline by the empty state and inside the status bar's drawer, so it is a light
4121
+ * list of its own rather than the entity's full List view, which is bound to the router outlet it is shown in.
4122
+ */
4123
+ export declare class WorkingContextPickerComponent implements OnInit {
4124
+ readonly contextName: import("@angular/core").InputSignal<string>;
4125
+ /** Emits once the selection went through — not when the user declined a confirmation. */
4126
+ readonly picked: import("@angular/core").OutputEmitterRef<string>;
4127
+ protected readonly searchKey: import("@angular/core").WritableSignal<string>;
4128
+ private readonly service;
4129
+ private readonly descriptorRegistry;
4130
+ private readonly definition;
4131
+ private readonly descriptor;
4132
+ private readonly store;
4133
+ private readonly activeId;
4134
+ private readonly allRows;
4135
+ protected readonly rows: import("@angular/core").Signal<PickerRow[]>;
4136
+ /** Recent ids the store still holds — a recent entity that has since been deleted is not offered. */
4137
+ protected readonly recentRows: import("@angular/core").Signal<PickerRow[]>;
4138
+ ngOnInit(): void;
4139
+ protected onSearch(event: Event): void;
4140
+ protected onPick(id: string): Promise<void>;
4141
+ protected testId(suffix: string): string;
4142
+ private rowOf;
4143
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextPickerComponent, never>;
4144
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextPickerComponent, "pp-working-context-picker", never, {
4145
+ "contextName": {
4146
+ "alias": "contextName";
4147
+ "required": true;
4148
+ "isSignal": true;
4149
+ };
4150
+ }, {
4151
+ "picked": "picked";
4152
+ }, never, never, true, never>;
4153
+ }
4154
+ /**
4155
+ * What a view that requires a context shows without one: "Select a …", with the picker right there. Picking
4156
+ * stays on the same view — the URL gains the context's id — so the user never takes a detour through a list.
4157
+ */
4158
+ export declare class WorkingContextEmptyStateComponent {
4159
+ protected readonly contextName: string;
4160
+ private readonly service;
4161
+ private readonly descriptorRegistry;
4162
+ private readonly transloco;
4163
+ protected readonly entityLabel: import("@angular/core").Signal<string>;
4164
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextEmptyStateComponent, never>;
4165
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextEmptyStateComponent, "pp-working-context-empty-state", never, {}, {}, never, never, true, never>;
4166
+ }
4167
+ interface WorkingContextPickerDialogData {
4168
+ contextName: string;
4169
+ /** The translated entity name, for the title. */
4170
+ entityLabel: string;
4171
+ }
4172
+ /** Dialog configuration that turns the picker into a full-height drawer on the right edge. */
4173
+ export declare const WORKING_CONTEXT_DRAWER_CONFIG: {
4174
+ readonly position: {
4175
+ readonly right: "0";
4176
+ readonly top: "0";
4177
+ };
4178
+ readonly height: "100%";
4179
+ readonly maxHeight: "100vh";
4180
+ readonly width: "420px";
4181
+ readonly maxWidth: "100vw";
4182
+ readonly panelClass: "pp-working-context-drawer";
4183
+ };
4184
+ /** The picker in a drawer, which the status bar's context crumb opens to switch. */
4185
+ export declare class WorkingContextPickerDialog {
4186
+ protected readonly data: WorkingContextPickerDialogData;
4187
+ protected readonly dialogRef: MatDialogRef<any, any>;
4188
+ private readonly router;
4189
+ private readonly routes;
4190
+ private readonly service;
4191
+ /** Where the context entity's own list is, when it has one. */
4192
+ protected listPath(): string | undefined;
4193
+ /** Leaves the drawer for the full list of the context's entity. */
4194
+ protected onShowList(): Promise<void>;
4195
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextPickerDialog, never>;
4196
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextPickerDialog, "pp-working-context-picker-dialog", never, {}, {}, never, never, true, never>;
4197
+ }
4198
+ /** An active working context as it is rendered: one crumb, with its badge and its extra text. */
4199
+ interface ContextCrumb {
4200
+ context: ActiveWorkingContext;
4201
+ title: string;
4202
+ /** The entity's translated name, shown as the crumb's tooltip. */
4203
+ label: string;
4204
+ badge: string | undefined;
4205
+ extra: string | undefined;
4206
+ /** What the entity can do next, from its state machine; empty when none governs it. */
4207
+ transitions: EntityStateTransition[];
4208
+ testId: string;
4209
+ }
4210
+ /**
4211
+ * The active working contexts, outermost first, as crumbs: the label, a badge, an extra text, and a menu to
4212
+ * switch (the picker as a drawer), open the entity for editing, or clear the context.
4213
+ *
4214
+ * It is the root of the status bar's breadcrumb — `BaseEntityStatusbarComponent` renders it before the entity
4215
+ * levels — and, in an application shell with a `statusbar` region, the whole content of that region, so the
4216
+ * context is visible on pages that have no entity form at all.
4217
+ */
4218
+ export declare class WorkingContextCrumbsComponent {
4219
+ readonly crumbs: Signal<ContextCrumb[]>;
4220
+ private readonly workingContext;
4221
+ protected readonly firing: import("@angular/core").WritableSignal<boolean>;
4222
+ private readonly dialog;
4223
+ private readonly router;
4224
+ private readonly entityRouteRegistry;
4225
+ private readonly transloco;
4226
+ /** Opens the context's picker as a drawer; picking in it switches, and closes it. */
4227
+ protected onSwitch(crumb: ContextCrumb): void;
4228
+ /** The context's entity in its own form, for editing it — the context stays active. */
4229
+ protected onOpen(crumb: ContextCrumb): Promise<void>;
4230
+ protected onFire(crumb: ContextCrumb, transition: EntityStateTransition): Promise<void>;
4231
+ protected onClear(crumb: ContextCrumb): Promise<void>;
4232
+ /** `badge: state` shows the state's name — "Running", not the key a machine stores — when the machine is known. */
4233
+ private badgeOf;
4234
+ private crumbOf;
4235
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextCrumbsComponent, never>;
4236
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextCrumbsComponent, "pp-working-context-crumbs", never, {}, {}, never, never, true, never>;
4237
+ }
4238
+ /**
4239
+ * The status bar of an application shell (its `statusbar` region): the active working contexts, on every page,
4240
+ * whether or not an entity form is open. Shown only while a context is active — an empty strip would be clutter.
4241
+ *
4242
+ * While it is on screen the status bar inside the entity tabs leaves the contexts to it, so they are not shown
4243
+ * twice; see {@link WorkingContextService.statusbarHostedByShell}.
4244
+ */
4245
+ export declare class WorkingContextStatusbarComponent {
4246
+ private readonly workingContext;
4247
+ protected readonly isVisible: import("@angular/core").Signal<boolean>;
4248
+ constructor();
4249
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextStatusbarComponent, never>;
4250
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextStatusbarComponent, "pp-working-context-statusbar", never, {}, {}, never, never, true, never>;
4251
+ }
4252
+ /** Route data: the context the collection belongs to. */
4253
+ export declare const CONTEXT_COLLECTION_CONTEXT_KEY = "collectionContext";
4254
+ /** Route data: the attribute of the context's entity that carries the collection. */
4255
+ export declare const CONTEXT_COLLECTION_PATH_KEY = "collectionPath";
4256
+ /** Route data: the embedded entity type of the collection's items. */
4257
+ export declare const CONTEXT_COLLECTION_ENTITY_KEY = "collectionEntity";
4258
+ /**
4259
+ * A list of the embedded collection of the **active** entity of a working context — the zones of the active
4260
+ * warehouse — with add, edit and remove acting on that entity alone: the user never selects a warehouse here, and a change sends
4261
+ * the item rather than the warehouse (see {@link EmbeddedCollectionService}).
4262
+ *
4263
+ * Everything comes from metadata: the route data names the context, the attribute and the item type, and the item
4264
+ * type's descriptor gives the columns and, in the dialog, the form. Without an active context the route never gets here —
4265
+ * `workingContextRoutes` shows its empty state instead.
4266
+ */
4267
+ export declare class ContextCollectionComponent {
4268
+ private readonly data;
4269
+ private readonly contextName;
4270
+ private readonly attrName;
4271
+ private readonly entityName;
4272
+ private readonly service;
4273
+ private readonly workingContext;
4274
+ private readonly descriptorRegistry;
4275
+ private readonly dialog;
4276
+ private readonly formNavigator;
4277
+ private readonly transloco;
4278
+ private readonly activeLang;
4279
+ protected readonly rows: import("@angular/core").WritableSignal<CollectionItem[]>;
4280
+ protected readonly isLoading: import("@angular/core").WritableSignal<boolean>;
4281
+ protected readonly error: import("@angular/core").WritableSignal<string | undefined>;
4282
+ private readonly context;
4283
+ private readonly descriptor;
4284
+ protected readonly columns: import("@angular/core").Signal<BaseEntityAttrDescriptor[]>;
4285
+ protected readonly displayedColumns: import("@angular/core").Signal<string[]>;
4286
+ protected readonly canChange: import("@angular/core").Signal<boolean>;
4287
+ /** Reloads whenever another entity becomes the active one — the list follows the context, not the other way round. */
4288
+ private readonly reloadOnContextChange;
4289
+ /** Opens a new row's form below the context; it saves the row on its own and returns here. */
4290
+ protected onAdd(): Promise<void>;
4291
+ /** Opens the row's own form — the screen its entity type has everywhere — below the context, with the owner in the URL. */
4292
+ protected onEdit(row: CollectionItem): Promise<void>;
4293
+ protected onDelete(row: CollectionItem): Promise<void>;
4294
+ protected testId(suffix: string): string;
4295
+ protected display(column: BaseEntityAttrDescriptor, row: CollectionItem): string;
4296
+ private rootEntityName;
4297
+ /**
4298
+ * The embedded form of a row: `<context url>/<item type>/<key>/details`, the URL chain the embedded screens read their
4299
+ * aggregate from. The navigator keeps the list's URL as where to return to.
4300
+ */
4301
+ private openForm;
4302
+ /** The key the URL addresses a row by: the attribute the owner's descriptor says identifies it, `id` otherwise. */
4303
+ private rowKey;
4304
+ /** Runs one change against the active entity, then shows what is stored now — the server's answer is the truth, also after a conflict. */
4305
+ private change;
4306
+ private reload;
4307
+ private messageOf;
4308
+ static ɵfac: i0.ɵɵFactoryDeclaration<ContextCollectionComponent, never>;
4309
+ static ɵcmp: i0.ɵɵComponentDeclaration<ContextCollectionComponent, "pp-context-collection", never, {}, {}, never, never, true, never>;
4310
+ }
4311
+ /**
4312
+ * The transitions the **active** entity of a working context can take — Open, Close — as buttons. Placed on
4313
+ * a page that declares them, so the user acts on the entity without reaching for the status bar's menu.
4314
+ *
4315
+ * It shows nothing without an active context, and nothing for an entity no state machine governs. `triggers` narrows the
4316
+ * offer to the named triggers, in that order; without it every transition the entity can take is offered. A transition a
4317
+ * guard refuses is shown disabled, with the reason as its tooltip.
4318
+ */
4319
+ export declare class WorkingContextActionsComponent {
4320
+ /** The context whose active entity the buttons act on. */
4321
+ readonly context: import("@angular/core").InputSignal<string>;
4322
+ /** The triggers to offer, in order; every available transition when absent. */
4323
+ readonly triggers: import("@angular/core").InputSignal<string[] | undefined>;
4324
+ private readonly workingContext;
4325
+ protected readonly firing: import("@angular/core").WritableSignal<boolean>;
4326
+ protected readonly transitions: import("@angular/core").Signal<import("@processpuzzle/base-entity").EntityStateTransition[]>;
4327
+ protected onFire(triggerKey: string): Promise<void>;
4328
+ protected testId(triggerKey: string): string;
4329
+ static ɵfac: i0.ɵɵFactoryDeclaration<WorkingContextActionsComponent, never>;
4330
+ static ɵcmp: i0.ɵɵComponentDeclaration<WorkingContextActionsComponent, "pp-working-context-actions", never, {
4331
+ "context": {
4332
+ "alias": "context";
4333
+ "required": true;
4334
+ "isSignal": true;
4335
+ };
4336
+ "triggers": {
4337
+ "alias": "triggers";
4338
+ "required": false;
4339
+ "isSignal": true;
4340
+ };
4341
+ }, {}, never, never, true, never>;
4342
+ }
4343
+ export type { ActiveWorkingContext, AddressFormat, ArtifactAttr, BaseEntity, BaseEntityDescriptorOptions, BaseEntityFacadeRegistry, BaseEntityLoadResponse, BaseEntityMapper, BaseEntityQueryCondition, CollectionItem, CollectionRead, DateFormat, DateStyle, DefinitionLookup, DynamicEntity, EmbeddedBreadcrumbLevel, EmbeddedChildRoute, EmbeddedPath, EmbeddedPathStep, EmbeddedRouteContext, EmbeddedRouteLevel, EmbeddedRow, EntityCalculatedControl, EntityComment, EntityDefinitionStatus, EntityOptions, EntityScreenRouteOptions, EntityScreens, EntityStateActions, EntityStateControl, EntityStateFireResult, EntityStateSnapshot, EntityStateTransition, EntityTabContributor, EntityTabDescriptor, EntityValueKind, EvaluatableRule, FilterCondition, FilterOperator, GeoLocation, GeoLocatorError, GeoPoint, HasUnsavedChanges, LocationSource, LookupTable, MapProvider, Multiplicity, MultiplicityHolder, NavigationPayload, NavigationState, ObjectUriResponse, OrderByCondition, PdfColumnDefinition, PdfExportDialogResult, PdfExportOptions, PdfExportResult, PersistedBaseEntity, PersistedEntity, PostalAddress, ResolvedDynamicEntity, ResolvedEmbeddedAggregate, RichTextContent, RuleEngine, RuleEvaluationResult, RuleSeverity, Selectable, SelectablesInput, TagSuggestionSource, TimeStyle, WorkingContextAggregate, WorkingContextDefinition, WorkingContextDisplay, WorkingContextPersistence, WorkingContextPicker, WorkingContextPickerDialogData, WorkingContextRouteLevel };
3951
4344
  //# sourceMappingURL=processpuzzle-base-entity.d.ts.map