@processpuzzle/base-entity 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @processpuzzle/base-entity
2
2
 
3
3
  ![Build and Test](https://github.com/ZsZs/processpuzzle/actions/workflows/build-base-entity-frontend.yml/badge.svg)
4
- [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=processpuzzle_base_entity&metric=alert_status)](https://sonarcloud.io/summary?id=processpuzzle_base_entity)
5
- [![Node version](https://img.shields.io/npm/v/%40processpuzzle%2Fbase-entity?style=flat)](https://www.npmjs.com/package/@processpuzzle/base-entity)
4
+ [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=processpuzzle_base_entity_frontend&metric=alert_status)](https://sonarcloud.io/summary?id=processpuzzle_base_entity_frontend)
5
+ [![npm version](https://img.shields.io/npm/v/%40processpuzzle%2Fbase-entity?style=flat)](https://www.npmjs.com/package/@processpuzzle/base-entity)
6
6
 
7
7
  ## Introduction
8
8
 
@@ -47,7 +47,7 @@ To plug the library into your application you provide an entity class, a mapper,
47
47
  <img src="https://github.com/ZsZs/processpuzzle/blob/develop/docs/base-entity-design_overview.png?raw=true" width=600px alt="Design Overview">
48
48
  </a>
49
49
 
50
- The snippets below are taken from the [TestEntity sample in the testbed](https://github.com/ZsZs/processpuzzle/tree/develop/apps/processpuzzle-testbed/src/app/content/base-forms/test-entity).
50
+ The snippets below are taken from the [TestEntity sample in the testbed](https://github.com/ZsZs/processpuzzle/tree/develop/apps/processpuzzle-testbed-frontend/src/app/content/base-forms/test-entity).
51
51
 
52
52
  ### 1. Define your entity
53
53
 
@@ -102,13 +102,18 @@ export class TestEntityMapper implements BaseEntityMapper<TestEntity> {
102
102
 
103
103
  ### 3. Extend the data service
104
104
 
105
- Pick `BaseEntityRestService` for an HTTP backend or `BaseEntityFirestoreService` for Firestore. Pass the mapper, a configuration key that resolves to the backend root URL, and the resource path.
105
+ Pick `BaseEntityRestService` for an HTTP backend or `BaseEntityFirestoreService` for Firestore. Pass the mapper, a configuration key that resolves to the root URL, and the resource path.
106
+
107
+ The key is a `BaseConfiguration` property name, resolved through `serviceRootOf`. Use
108
+ `BACKEND_SERVICE_ROOT` for a resource served by the platform's own backend — or the optional
109
+ per-feature root of the owning feature, which falls back to it. Use `THIRD_PARTY_ROOT` for a
110
+ third-party source, as the example below does: `test-entity` is one of the json-server resources.
106
111
 
107
112
  ```typescript
108
113
  @Injectable({ providedIn: 'root' })
109
114
  export class TestEntityService extends BaseEntityRestService<TestEntity> {
110
115
  constructor(protected override entityMapper: TestEntityMapper) {
111
- super(entityMapper, 'BACKEND_SERVICE_ROOT', 'test-entity');
116
+ super(entityMapper, 'THIRD_PARTY_ROOT', 'test-entity');
112
117
  }
113
118
  }
114
119
  ```
@@ -132,7 +137,7 @@ export const TestEntityStore = signalStore(
132
137
 
133
138
  ### 5. Describe the attributes
134
139
 
135
- Each visible field gets a `BaseEntityAttrDescriptor`. `FormControlType` covers `TEXT_BOX`, `TEXTAREA`, `CHECKBOX`, `DATE`, `DROPDOWN`, `LOOKUP`, `RADIO`, `TAGS`, `ARTIFACT`, `COMPONENTS`, `FOREIGN_KEY`, `LABEL`, `TITLE`, and `FLEX_BOX`. Use `FlexboxDescriptor` to lay attributes out in rows and columns, and `linkedEntityType` (a string — the related entity's name) to point at a related entity (used by `LOOKUP`, `FOREIGN_KEY`, and nested `COMPONENTS`). The descriptor is resolved at runtime through `BASE_ENTITY_FACADE_REGISTRY`.
140
+ Each visible field gets a `BaseEntityAttrDescriptor` whose `FormControlType` picks the control (full list and behavior in [Control types](#control-types)). Use `FlexboxDescriptor` to lay attributes out in rows and columns, and `linkedEntityType` (a string — the related entity's name) to point at another entity (used by `LOOKUP`, `FOREIGN_KEY`, `RELATED_ENTITIES`, `COMPONENTS`, and `EMBEDDED_COMPONENTS`). The descriptor is resolved at runtime through `BASE_ENTITY_FACADE_REGISTRY`.
136
141
 
137
142
  ```typescript
138
143
  function createTestEntityAttrDescriptors(): AbstractAttrDescriptor[] {
@@ -144,13 +149,17 @@ function createTestEntityAttrDescriptors(): AbstractAttrDescriptor[] {
144
149
  const dateAttr = new BaseEntityAttrDescriptor('date', FormControlType.DATE, 'Date', undefined, false, { inputType: 'date' });
145
150
  const lookupAttr = new BaseEntityAttrDescriptor('lookup', FormControlType.LOOKUP, 'Lookup');
146
151
  const enumAttr = new BaseEntityAttrDescriptor('enumValue', FormControlType.DROPDOWN, 'Enum', selectables);
152
+ const relatedEntitiesAttr = new BaseEntityAttrDescriptor('relatedEntities', FormControlType.RELATED_ENTITIES, 'Related Entities');
147
153
  const componentsAttr = new BaseEntityAttrDescriptor('components', FormControlType.COMPONENTS, 'Components');
154
+ const embeddedComponentsAttr = new BaseEntityAttrDescriptor('embeddedComponents', FormControlType.EMBEDDED_COMPONENTS, 'Embedded Components');
148
155
 
149
156
  lookupAttr.linkedEntityType = 'Trunk Data';
157
+ relatedEntitiesAttr.linkedEntityType = 'Related Entity';
150
158
  componentsAttr.linkedEntityType = 'Test Entity Component';
159
+ embeddedComponentsAttr.linkedEntityType = 'Embedded Component';
151
160
 
152
161
  const column1 = new FlexboxDescriptor([nameAttr, descriptionAttr, booleanAttr], FlexDirection.COLUMN);
153
- const column2 = new FlexboxDescriptor([numberAttr, dateAttr, lookupAttr, enumAttr, componentsAttr], FlexDirection.COLUMN);
162
+ const column2 = new FlexboxDescriptor([numberAttr, dateAttr, lookupAttr, enumAttr, relatedEntitiesAttr, componentsAttr, embeddedComponentsAttr], FlexDirection.COLUMN);
154
163
  const layout = new FlexboxDescriptor([column1, column2], FlexDirection.CONTAINER);
155
164
  layout.style = { 'column-gap': '20px' };
156
165
  return [layout];
@@ -211,6 +220,232 @@ export class TestEntityFacade extends BaseEntityFacade<TestEntity> {
211
220
 
212
221
  The facade can then be provided through the `ACTIVE_ENTITY_FACADE` token, and `BaseEntityContainerComponent` will resolve its descriptor automatically — no per-entity container component required.
213
222
 
223
+ ## Control types
224
+
225
+ Every attribute's `FormControlType` selects the component that renders it in the generated form. The builder creates a reactive `FormControl` under `attrName` for each descriptor and instantiates the mapped component; **an unmapped type throws `Undefined form control type`**.
226
+
227
+ | Type | Renders | Value shape | Required props | Notes |
228
+ | --- | --- | --- | --- | --- |
229
+ | `TEXT_BOX` | `matInput` text field | `string` | `label` | `options.inputType` sets the HTML input type (e.g. `number`). |
230
+ | `TEXTAREA` | `matInput` textarea | `string` | `label` | `lines` sets the row count; `placeholder` the hint. |
231
+ | `CHECKBOX` | `mat-checkbox` | `boolean` | `label` | |
232
+ | `DATE` | `matInput` + `mat-datepicker` | `Date` | `label` | Format is governed by the ambient Material date adapter. |
233
+ | `DROPDOWN` | `mat-select` | selected option's `value` | **`selectables`** | Options come from `selectables` (array or `() => Selectable[]`). |
234
+ | `RADIO` | native radio group | selectable `key` | **`selectables`** | Reactive; stores the `key` of the chosen option. |
235
+ | `TITLE` | `<h2>` section heading (display only) | — | `label` | Renders `label` as a form section title. |
236
+ | `TAGS` | `mat-chip-grid` | `string[]` | `label` | ENTER/COMMA add a chip; chips are editable/removable. |
237
+ | `LABEL` | `<h3>`/`<p>` (display only) | `string` | `label` | `isHeading` renders a heading instead of a paragraph. |
238
+ | `FLEX_BOX` | layout container | — (no control) | uses `FlexboxDescriptor` | Grouping only; recurses into children. See below. |
239
+ | `LOOKUP` | autocomplete over a lookup table | lookup **`key`** (`string`) | **`linkedEntityType`** | Tricky — see below. |
240
+ | `FOREIGN_KEY` | read-only field + Select/link buttons | related entity **`id`** (`string`) | **`linkedEntityType`** | To-one reference; picks via the navigator. |
241
+ | `RELATED_ENTITIES` | list of related-entity rows | array of related **ids** | **`linkedEntityType`**, `referenceIdField` | To-many **association**; the related entities exist independently. |
242
+ | `COMPONENTS` | list of component rows | array of component **ids** | **`linkedEntityType`**, `referenceIdField` | To-many **containment**, child in its own table. Attaching stamps the parent's id into the child's foreign key; deleting destroys the child. |
243
+ | `EMBEDDED_COMPONENTS` | inline sub-form per component | array of the **children themselves** | **`linkedEntityType`** | To-many **containment**, child inside the parent's payload. Backed by a `FormArray`; saved and deleted with the parent. |
244
+ | `ARTIFACT` | file thumbnail/icon + upload/delete | `ArtifactAttr` (or `null`) | `label`, `showThumbnail` | Tricky — see below. |
245
+ | `ADDITIONAL_PROPERTIES` | editable key/value list | `Record<string,string>` | `label` | Free-form string map. |
246
+
247
+ `linkedEntityType` is **mandatory** for `LOOKUP`, `FOREIGN_KEY`, `RELATED_ENTITIES`, `COMPONENTS`, and `EMBEDDED_COMPONENTS` — it names the other entity, whose descriptor is resolved at runtime through `BASE_ENTITY_FACADE_REGISTRY` (or, for an embedded component, through `EMBEDDED_ENTITY_DESCRIPTOR_REGISTRY`); omitting it throws.
248
+
249
+ ### Association vs. containment
250
+
251
+ Three control types render a to-many list, and which one is right follows from **who owns the rows**:
252
+
253
+ | Control type | Relationship | Add | Delete | Persisted by |
254
+ | --- | --- | --- | --- | --- |
255
+ | `RELATED_ENTITIES` | **association** — the target lives on its own | picks an existing entity through the navigator | detaches the reference only | the target's own save, independently |
256
+ | `COMPONENTS` | **containment**, child in its own table | picks/creates a child, then stamps this entity's id into the child's foreign key | destroys the child (after confirmation) | the child's own endpoint |
257
+ | `EMBEDDED_COMPONENTS` | **containment**, child in this payload | appends an empty inline sub-form | drops the row | this entity's save |
258
+
259
+ The two containment types are the two variations of a **component** — a part that belongs to exactly one
260
+ parent — and the child's own descriptor says which it is through `componentParent` / `isEmbedded` (see
261
+ [Component entities](#component-entities)). The declarations are on opposite sides of the relationship and are
262
+ both hand-written, so each control **checks that they agree at first render** and throws, naming both sides,
263
+ when they do not:
264
+
265
+ - the child entity has no descriptor in either registry;
266
+ - the child does not name this entity in its `componentParent`;
267
+ - `COMPONENTS` points at an `isEmbedded` child (use `EMBEDDED_COMPONENTS`), or `EMBEDDED_COMPONENTS` points at
268
+ one that is not (use `COMPONENTS`).
269
+
270
+ `Test Entity` in the [testbed](../../../apps/processpuzzle-testbed-frontend) demonstrates all three side by side —
271
+ `relatedEntities` → `Related Entity`, `components` → `Test Entity Component`, `embeddedComponents` →
272
+ `Embedded Component`.
273
+
274
+ ### FLEX_BOX (layout)
275
+
276
+ `FLEX_BOX` uses a `FlexboxDescriptor` (not a `BaseEntityAttrDescriptor`) and carries **no value**. It nests child descriptors and a `FlexDirection` (`CONTAINER` / `COLUMN` / `ROW`); the builder recurses, rendering the children into the *same* form group. Use it to arrange fields in rows and columns (see the `createTestEntityAttrDescriptors` example above).
277
+
278
+ ### The tricky ones
279
+
280
+ - **`LOOKUP`** uses a **two-control design**: the visible autocomplete text is a private `displayControl` decoupled from the real `FormControl`, which stores the lookup **key**. An `effect()` keeps them in sync. The lookup table (`{ key, value, description? }`) is loaded on init from the store resolved via `linkedEntityType`; the display shows `value`, the form holds `key`. The link icon navigates to the related entity.
281
+ - **`FOREIGN_KEY`** shows the related entity's identifying text (read-only) with the real id in a hidden control. The **Select** button snapshots the form and navigates to the related list (`SELECT_OR_CREATE`); on return the chosen id is written back to both the entity and the control. A link icon navigates to the current reference.
282
+ - **`RELATED_ENTITIES`** is the to-many analogue: it normalizes heterogeneous items (strings/objects) into `{ id }` using `referenceIdField`, appends via the same navigator round-trip, and each row has a link and a delete button that detaches the reference only.
283
+ - **`COMPONENTS`** looks like `RELATED_ENTITIES` but owns its rows. It resolves each row's text through the child's store (loading it if the parent's form is the first screen opened) and falls back to the id; **Add** takes the same navigator round-trip and then writes the parent's id into the attribute named by the child's `parentReferenceAttrName()`; **Delete** confirms and then calls the child store's `delete`. Like `ARTIFACT`, it therefore has an **immediate backend side-effect**, before the parent is saved.
284
+ - **`EMBEDDED_COMPONENTS`** is the only control backed by a **`FormArray`** rather than a `FormControl`: each row is a sub-form built from the child's descriptor with the same `BaseEntityFormBuilder`, so the children are already part of `form.value` (no imperative write-back) and a child's `required` attribute keeps the *parent's* Save disabled. The sub-forms are handed the **parent's** store — an embedded child has none of its own. Rows are seeded from the attribute's value, which is also what restores them from a form snapshot.
285
+ - **`ARTIFACT`** binds an `ArtifactAttr` (`{ bucket, objectId, name, mimeType }`). It fetches a thumbnail only for `image/*` types when `showThumbnail !== false`, otherwise shows a MIME-type icon; upload delegates to `ArtifactSelectorComponent` and **delete actually removes the stored object** (after a confirmation dialog). With `isHeading` it degrades to a plain heading. Requires an `ObjectStoreService` provider.
286
+
287
+ These value-editing controls (`ARTIFACT`, `LOOKUP`, `FOREIGN_KEY`, `RELATED_ENTITIES`, `COMPONENTS`, `TAGS`, `ADDITIONAL_PROPERTIES`) write to their `FormControl` **imperatively** (`setValue` + `markAsDirty`), which is why the form's Save button reacts to `form.events` rather than a plain dirty binding. `EMBEDDED_COMPONENTS` is the exception: its `FormArray` is edited by the sub-forms themselves.
288
+
289
+ > **Note.** `DATE` display/parse format follows Angular Material's ambient date adapter (`MAT_DATE_FORMATS`), configured app-wide rather than per field, so the descriptor's `format` property is not applied here.
290
+
291
+ ## Component entities
292
+
293
+ Most entities are aggregate roots — they stand on their own and are reached from their own list. A
294
+ **component** is a part: it belongs to exactly one parent, is created from the parent's form, and is deleted
295
+ outright rather than merely detached when the user removes it there. Two `BaseEntityDescriptor` options
296
+ declare that:
297
+
298
+ | Option | Type | Meaning |
299
+ | --- | --- | --- |
300
+ | `componentParent` | `string \| string[]` | Entity name(s) that may aggregate this one. A list is allowed because one component *type* can be hosted by several parent types (an `App Widget` sits under `App Region`, `App Page` and `App Widget`) — the 1:N invariant holds per *instance*, not per type. Undefined for a stand-alone entity. |
301
+ | `isEmbedded` | `boolean` | `true` when the payload travels inside the parent's payload — no endpoint and no store of its own, and the parent's save persists it. `false` (default) when the component is persisted on its own and points back at its parent through a `FOREIGN_KEY` attribute. Declaring it without `componentParent` throws. |
302
+
303
+ ```typescript
304
+ // Embedded: an App Region has no endpoint; it is a slot inside the App Definition document.
305
+ new BaseEntityDescriptor({ entityName: 'App Region', attrDescriptors, componentParent: 'App Definition', isEmbedded: true });
306
+
307
+ // Not embedded: persisted through its own store, with `testEntityId` as the key back to the parent.
308
+ new BaseEntityDescriptor({ entityName: 'Test Entity Component', attrDescriptors, componentParent: 'Test Entity', isEmbedded: false });
309
+ ```
310
+
311
+ The parent points back at the component with a `COMPONENTS` (not embedded) or `EMBEDDED_COMPONENTS` (embedded)
312
+ attribute — see [Association vs. containment](#association-vs-containment) for what the two control types do and
313
+ for the errors thrown when the two declarations disagree.
314
+
315
+ Derived from those two:
316
+
317
+ - **`isComponent()`** / **`isComponentOf(entityName)`** — containment predicates.
318
+ - **`parentReferenceAttrName()`** — the `FOREIGN_KEY` attribute pointing at one of the `componentParent`s,
319
+ found through nested `FlexboxDescriptor`s. `undefined` for a stand-alone entity, and for an embedded
320
+ component, which is located by its position in the parent's payload rather than by a key.
321
+
322
+ > **`componentParent` is not `parentEntity`.** `parentEntity` names the **inheritance** supertype and pairs
323
+ > with `isAbstract`; `componentParent` names the **aggregator**. An entity can legitimately have both.
324
+
325
+ Both properties are serialized by `EntityRegistryComponent`, so a Low-Code designer reading the registry sees
326
+ the containment graph alongside the inheritance one.
327
+
328
+ ### Registering an embedded component
329
+
330
+ A non-embedded component is a normal entity: it has a service, a store and therefore a facade, and its
331
+ descriptor is resolved through `BASE_ENTITY_FACADE_REGISTRY` like any other. An **embedded** one has nothing to
332
+ put in a facade — no endpoint, no store — yet the parent's form still has to resolve its descriptor to render
333
+ the sub-forms. It is registered instead in `EMBEDDED_ENTITY_DESCRIPTOR_REGISTRY`:
334
+
335
+ ```typescript
336
+ {
337
+ provide: EMBEDDED_ENTITY_DESCRIPTOR_REGISTRY,
338
+ useValue: { 'Embedded Component': createEmbeddedComponentDescriptor },
339
+ }
340
+ ```
341
+
342
+ - The values are **factories** (`() => BaseEntityDescriptor`), not instances, because a containment graph may be
343
+ cyclic (`App Definition` → `App Region` → `App Widget` → `App Widget`), which eager values cannot express.
344
+ `BaseEntityDescriptorRegistry` memoizes what a factory returns, so the descriptor's identity is stable across
345
+ renders.
346
+ - `BaseEntityDescriptorRegistry.getDescriptor()` consults the facade registry **first** and falls back to this
347
+ one; `getStore()` keeps returning `undefined` for an embedded entity.
348
+ - Such an entity needs no route, container component, service or store — only the entity class, its mapper and
349
+ its descriptor. Its i18n scope is loaded on the **parent's** route, since its labels are rendered there.
350
+ - `EntityRegistryComponent` serializes it too, with no `route`, and the generated e2e list/CRUD suites skip
351
+ `isEmbedded` entities because there is no page to visit.
352
+
353
+ ## Per-field styling
354
+
355
+ Two descriptor properties give a consumer per-attribute style control, applied via `[ngClass]`:
356
+
357
+ - **`styleClass`** — class(es) on the field **wrapper** (`fieldset` / `mat-form-field` / the radio container).
358
+ - **`labelClass`** — class(es) on the field **label** (`legend` / `mat-label` / checkbox label).
359
+
360
+ There is also a `style` property bound with `[ngStyle]` for one-off inline styles.
361
+
362
+ ```typescript
363
+ const expr = new BaseEntityAttrDescriptor('expression', FormControlType.TEXTAREA, 'Expression');
364
+ expr.styleClass = 'monospace full-width';
365
+ expr.labelClass = 'muted';
366
+ ```
367
+
368
+ > **These classes must be defined in a global stylesheet** (your app's `styles.scss` / the `styles` array), **not** in a component's encapsulated `.css`. The classes land on the *library's* DOM elements; Angular's emulated view encapsulation scopes a component's own styles to that component's elements, so a component-scoped `.monospace` rule would be applied to the field but never match it. Global styles (or `ViewEncapsulation.None`) are the reliable seam — prefer this over reaching into the library's internal tags, which are not a stable contract.
369
+
370
+ ## Internationalisation
371
+
372
+ Entity names (shown in the tabs) and attribute labels (column headers and form labels) can be translated by the **consuming application** through [Transloco](https://jsverse.github.io/transloco/). The library follows **convention over configuration**: the key root is derived from the `entityName`, and you only provide the matching translation files — no per-field wiring. When a key is missing, the raw `entityName` / `label` from the descriptor is used as the fallback, so translation is entirely opt-in.
373
+
374
+ ### 1. Key root is derived from the entity name
375
+
376
+ The transloco key root is `snake_underscore(entityName)` — `"Trunk Data"` → `trunk_data`, `"OrderLine"` → `order_line`. No configuration is needed; just name the Transloco scope to match. Set `i18nScope` on the descriptor only to **override** the derived root (e.g. when the registered scope name differs from the convention, or when the derived root would collide with the library's own `base_entity` scope).
377
+
378
+ ```typescript
379
+ new BaseEntityDescriptor({
380
+ entityName: 'Trunk Data',
381
+ attrDescriptors: createTrunkDataAttrDescriptors(),
382
+ // key root → 'trunk_data' (derived); pass i18nScope only to override
383
+ });
384
+ ```
385
+
386
+ ### 2. Provide the Transloco scope on the route
387
+
388
+ The scope must be provided where the components render (typically the routed feature). **Always set `alias` explicitly** — Transloco camelCases the default alias, which silently breaks names containing `-` or `_`.
389
+
390
+ ```typescript
391
+ {
392
+ path: 'trunk_data',
393
+ providers: [provideTranslocoScope({ scope: 'trunk_data', alias: 'trunk_data' })],
394
+ // …
395
+ }
396
+ ```
397
+
398
+ ### 3. Add the translation files
399
+
400
+ Transloco loads scoped files from `assets/i18n/<scope>/<lang>.json`. Because the scope (= derived key root) already identifies the entity, keys are **rooted at the scope** (Transloco prepends the scope automatically, so the file content is flat — no entity wrapper):
401
+
402
+ - **Entity name** → `<scope>._self` (the reserved `_self` avoids colliding with the attribute keys)
403
+ - **Attribute label** → `<scope>.<attrName>`
404
+
405
+ where `<attrName>` is the attribute's `attrName` (a code identifier — no spaces, no display strings). An attribute's `labelKey` overrides its own segment (replaces `attrName`); use plain identifiers — spaces are not valid in Transloco keys.
406
+
407
+ ```jsonc
408
+ // assets/i18n/trunk_data/en.json → keys trunk_data._self, trunk_data.key, …
409
+ {
410
+ "_self": "Trunk Data", // entity name in the tabs
411
+ "key": "Reference Key", // attribute labels, keyed by attrName
412
+ "description": "Description",
413
+ "value": "Value"
414
+ }
415
+ ```
416
+
417
+ ### The library's own strings
418
+
419
+ Everything the library renders that is *not* derived from a descriptor — toolbar labels and tooltips, PDF-export
420
+ and RSQL dialogs, the delete-confirmation dialogs, and the list/details tab captions — lives in the `base_entity` scope shipped with the package
421
+ (`assets/i18n/base_entity/<lang>.json`, copied into your build). Provide it once on the route that hosts the
422
+ entity screens:
423
+
424
+ ```typescript
425
+ providers: [provideTranslocoScope({ scope: 'base_entity', alias: 'base_entity' })];
426
+ ```
427
+
428
+ The tab captions take the resolved entity name as a parameter, so translators control the word order:
429
+
430
+ ```jsonc
431
+ "tabs": {
432
+ "list": "{{ entity }} - list", // → "Trunk Data - list"
433
+ "details": "{{ entity }} - details"
434
+ }
435
+ ```
436
+
437
+ ## Status-bar title
438
+
439
+ The status bar labels the selected entity with the value of one identifying attribute. That attribute
440
+ is `titleKey` on the descriptor, defaulting to the `isLinkToDetails` attribute (the same one
441
+ `componentIdentification()` returns). Set `titleKey` only to point at a different attribute; set the
442
+ `entityTitle` string/function to override the displayed text entirely.
443
+
444
+ ```typescript
445
+ new BaseEntityDescriptor({ entityName: 'Order Line', attrDescriptors, titleKey: 'productName' });
446
+ // status bar shows currentEntity().productName
447
+ ```
448
+
214
449
  ## RSQL search
215
450
 
216
451
  The list toolbar carries two independent search inputs:
@@ -242,7 +477,7 @@ The **✎ (`edit_note`)** button in the query field opens the **advanced query e
242
477
  - **Live linting** — structural validation (paren balance, clause ordering, unterminated strings) plus semantic checks (unknown field, operator not allowed for the field's type). **Apply** stays disabled while the expression is invalid.
243
478
  - A **sample query** inserted on <kbd>Tab</kbd> in an empty editor, plus a matching placeholder.
244
479
 
245
- Both the autocomplete and the linter are driven by field metadata derived from the entity's descriptor by `DescriptorBackedFieldMetadataProvider`: each `BaseEntityAttrDescriptor` maps to an RSQL field whose type (and therefore its allowed operators) comes from the `FormControlType` — `CHECKBOX`→boolean, `DATE`→date, `DROPDOWN`/`RADIO`→enum (enum values taken from the attribute's selectables), a numeric/date `TEXT_BOX` input type→number/date, everything else→string. Presentation-only controls (`ARTIFACT`, `COMPONENTS`, `FLEX_BOX`, `LABEL`, `TITLE`) are excluded from the searchable fields.
480
+ Both the autocomplete and the linter are driven by field metadata derived from the entity's descriptor by `DescriptorBackedFieldMetadataProvider`: each `BaseEntityAttrDescriptor` maps to an RSQL field whose type (and therefore its allowed operators) comes from the `FormControlType` — `CHECKBOX`→boolean, `DATE`→date, `DROPDOWN`/`RADIO`→enum (enum values taken from the attribute's selectables), a numeric/date `TEXT_BOX` input type→number/date, everything else→string. Presentation-only controls (`ARTIFACT`, `FLEX_BOX`, `LABEL`, `RELATED_ENTITIES`, `TITLE`) are excluded from the searchable fields.
246
481
 
247
482
  To use the editor outside the entity toolbar, provide your own `RsqlFieldMetadataProvider` and bind `RsqlQueryEditorComponent` through a reactive `FormControl` (see `query-editor/example-usage.ts`).
248
483
 
@@ -1,13 +1,61 @@
1
1
  {
2
+ "entity_attribute": {
3
+ "_self": "Attribut",
4
+ "code": "Code",
5
+ "name": "Name",
6
+ "valueKind": "Wertart",
7
+ "formControlType": "Steuerelementtyp",
8
+ "displayOrder": "Anzeigereihenfolge",
9
+ "required": "Erforderlich",
10
+ "isMultiValued": "Mehrwertig",
11
+ "indexed": "Indiziert",
12
+ "isLinkToDetails": "Benennt den Datensatz",
13
+ "linkedEntityType": "Verknüpfte Entität",
14
+ "defaultValue": "Standardwert",
15
+ "enumValues": "Aufzählungswerte"
16
+ },
17
+ "entity_definition": {
18
+ "_self": "Entitätsdefinition",
19
+ "code": "Code",
20
+ "name": "Name",
21
+ "description": "Beschreibung",
22
+ "status": "Status",
23
+ "isEmbedded": "Eingebettet",
24
+ "componentParents": "Übergeordnete Komponenten",
25
+ "attributes": "Attribute",
26
+ "version": "Version",
27
+ "updatedAt": "Aktualisiert am"
28
+ },
29
+ "artifact": {
30
+ "upload_failure": "Hochladen des Artefakts fehlgeschlagen. Bitte erneut versuchen."
31
+ },
2
32
  "delete_artifact_confirmation_dialog": {
3
33
  "title": "Artefakt löschen?",
4
34
  "content": "Dadurch wird „{{ artifactName }}\" dauerhaft aus dem Objektspeicher gelöscht.",
5
35
  "cancel_button": "Abbrechen",
6
36
  "delete_button": "Löschen"
7
37
  },
38
+ "delete_component_confirmation_dialog": {
39
+ "title": "Komponente löschen?",
40
+ "content": "Dadurch wird „{{ componentName }}\" dauerhaft gelöscht – eine Komponente gehört ausschließlich zu diesem Datensatz.",
41
+ "cancel_button": "Abbrechen",
42
+ "delete_button": "Löschen"
43
+ },
44
+ "statusbar": {
45
+ "breadcrumb_label": "Datensatz-Hierarchie"
46
+ },
47
+ "tabs": {
48
+ "list": "{{ entity }} - Liste",
49
+ "details": "{{ entity }} - Details"
50
+ },
8
51
  "toolbar": {
9
52
  "query_label": "Abfrage",
10
- "filter_label": "Filter"
53
+ "query_tooltip": "Liste mit einem RSQL-Ausdruck abfragen",
54
+ "filter_label": "Filter",
55
+ "filter_tooltip": "Geladene Zeilen nach Text filtern",
56
+ "edit_tooltip": "Ausgewählten Datensatz bearbeiten",
57
+ "new_tooltip": "Neuen Datensatz erstellen",
58
+ "delete_tooltip": "Ausgewählte Datensätze löschen"
11
59
  },
12
60
  "pdf_export": {
13
61
  "button": "PDF",
@@ -28,5 +76,8 @@
28
76
  "title": "Erweiterter Abfrage-Editor",
29
77
  "cancel_button": "Abbrechen",
30
78
  "apply_button": "Übernehmen"
79
+ },
80
+ "embedded_components": {
81
+ "save_owner_first": "Speichern Sie diesen Datensatz, bevor Sie {{ entity }} hinzufügen — eine eingebettete Komponente wird darin gespeichert."
31
82
  }
32
83
  }
@@ -1,13 +1,61 @@
1
1
  {
2
+ "entity_attribute": {
3
+ "_self": "Attribute",
4
+ "code": "Code",
5
+ "name": "Name",
6
+ "valueKind": "Value Kind",
7
+ "formControlType": "Control Type",
8
+ "displayOrder": "Display Order",
9
+ "required": "Required",
10
+ "isMultiValued": "Multi-valued",
11
+ "indexed": "Indexed",
12
+ "isLinkToDetails": "Titles the record",
13
+ "linkedEntityType": "Linked Entity",
14
+ "defaultValue": "Default Value",
15
+ "enumValues": "Enum Values"
16
+ },
17
+ "entity_definition": {
18
+ "_self": "Entity Definition",
19
+ "code": "Code",
20
+ "name": "Name",
21
+ "description": "Description",
22
+ "status": "Status",
23
+ "isEmbedded": "Embedded",
24
+ "componentParents": "Component Parents",
25
+ "attributes": "Attributes",
26
+ "version": "Version",
27
+ "updatedAt": "Updated At"
28
+ },
29
+ "artifact": {
30
+ "upload_failure": "Artifact upload failed. Please try again."
31
+ },
2
32
  "delete_artifact_confirmation_dialog": {
3
33
  "title": "Delete artifact?",
4
34
  "content": "This will permanently delete \"{{ artifactName }}\" from the object store.",
5
35
  "cancel_button": "Cancel",
6
36
  "delete_button": "Delete"
7
37
  },
38
+ "delete_component_confirmation_dialog": {
39
+ "title": "Delete component?",
40
+ "content": "This will permanently delete \"{{ componentName }}\" — a component belongs to this record only.",
41
+ "cancel_button": "Cancel",
42
+ "delete_button": "Delete"
43
+ },
44
+ "statusbar": {
45
+ "breadcrumb_label": "Record hierarchy"
46
+ },
47
+ "tabs": {
48
+ "list": "{{ entity }} - list",
49
+ "details": "{{ entity }} - details"
50
+ },
8
51
  "toolbar": {
9
52
  "query_label": "Query",
10
- "filter_label": "Filter"
53
+ "query_tooltip": "Query the list with an RSQL expression",
54
+ "filter_label": "Filter",
55
+ "filter_tooltip": "Filter the loaded rows by text",
56
+ "edit_tooltip": "Edit the selected record",
57
+ "new_tooltip": "Create a new record",
58
+ "delete_tooltip": "Delete the selected records"
11
59
  },
12
60
  "pdf_export": {
13
61
  "button": "PDF",
@@ -28,5 +76,8 @@
28
76
  "title": "Advanced query editor",
29
77
  "cancel_button": "Cancel",
30
78
  "apply_button": "Apply"
79
+ },
80
+ "embedded_components": {
81
+ "save_owner_first": "Save this record before adding {{ entity }} — an embedded component is stored inside it."
31
82
  }
32
83
  }
@@ -1,13 +1,61 @@
1
1
  {
2
+ "entity_attribute": {
3
+ "_self": "Atributo",
4
+ "code": "Código",
5
+ "name": "Nombre",
6
+ "valueKind": "Tipo de valor",
7
+ "formControlType": "Tipo de control",
8
+ "displayOrder": "Orden de visualización",
9
+ "required": "Obligatorio",
10
+ "isMultiValued": "Multivalor",
11
+ "indexed": "Indexado",
12
+ "isLinkToDetails": "Titula el registro",
13
+ "linkedEntityType": "Entidad vinculada",
14
+ "defaultValue": "Valor predeterminado",
15
+ "enumValues": "Valores de enumeración"
16
+ },
17
+ "entity_definition": {
18
+ "_self": "Definición de entidad",
19
+ "code": "Código",
20
+ "name": "Nombre",
21
+ "description": "Descripción",
22
+ "status": "Estado",
23
+ "isEmbedded": "Incrustada",
24
+ "componentParents": "Componentes padre",
25
+ "attributes": "Atributos",
26
+ "version": "Versión",
27
+ "updatedAt": "Actualizado el"
28
+ },
29
+ "artifact": {
30
+ "upload_failure": "Error al subir el artefacto. Inténtelo de nuevo."
31
+ },
2
32
  "delete_artifact_confirmation_dialog": {
3
33
  "title": "¿Eliminar artefacto?",
4
34
  "content": "Esto eliminará permanentemente \"{{ artifactName }}\" del almacén de objetos.",
5
35
  "cancel_button": "Cancelar",
6
36
  "delete_button": "Eliminar"
7
37
  },
38
+ "delete_component_confirmation_dialog": {
39
+ "title": "¿Eliminar componente?",
40
+ "content": "Esto eliminará permanentemente \"{{ componentName }}\": un componente pertenece solo a este registro.",
41
+ "cancel_button": "Cancelar",
42
+ "delete_button": "Eliminar"
43
+ },
44
+ "statusbar": {
45
+ "breadcrumb_label": "Jerarquía de registros"
46
+ },
47
+ "tabs": {
48
+ "list": "{{ entity }} - lista",
49
+ "details": "{{ entity }} - detalles"
50
+ },
8
51
  "toolbar": {
9
52
  "query_label": "Consulta",
10
- "filter_label": "Filtro"
53
+ "query_tooltip": "Consultar la lista con una expresión RSQL",
54
+ "filter_label": "Filtro",
55
+ "filter_tooltip": "Filtrar las filas cargadas por texto",
56
+ "edit_tooltip": "Editar el registro seleccionado",
57
+ "new_tooltip": "Crear un nuevo registro",
58
+ "delete_tooltip": "Eliminar los registros seleccionados"
11
59
  },
12
60
  "pdf_export": {
13
61
  "button": "PDF",
@@ -28,5 +76,8 @@
28
76
  "title": "Editor de consultas avanzado",
29
77
  "cancel_button": "Cancelar",
30
78
  "apply_button": "Aplicar"
79
+ },
80
+ "embedded_components": {
81
+ "save_owner_first": "Guarde este registro antes de añadir {{ entity }}: un componente incrustado se almacena dentro de él."
31
82
  }
32
83
  }
@@ -1,13 +1,61 @@
1
1
  {
2
+ "entity_attribute": {
3
+ "_self": "Attribut",
4
+ "code": "Code",
5
+ "name": "Nom",
6
+ "valueKind": "Type de valeur",
7
+ "formControlType": "Type de contrôle",
8
+ "displayOrder": "Ordre d'affichage",
9
+ "required": "Obligatoire",
10
+ "isMultiValued": "Multivaleur",
11
+ "indexed": "Indexé",
12
+ "isLinkToDetails": "Titre de l'enregistrement",
13
+ "linkedEntityType": "Entité liée",
14
+ "defaultValue": "Valeur par défaut",
15
+ "enumValues": "Valeurs d'énumération"
16
+ },
17
+ "entity_definition": {
18
+ "_self": "Définition d'entité",
19
+ "code": "Code",
20
+ "name": "Nom",
21
+ "description": "Description",
22
+ "status": "Statut",
23
+ "isEmbedded": "Intégrée",
24
+ "componentParents": "Composants parents",
25
+ "attributes": "Attributs",
26
+ "version": "Version",
27
+ "updatedAt": "Mis à jour le"
28
+ },
29
+ "artifact": {
30
+ "upload_failure": "Échec du téléversement de l'artefact. Veuillez réessayer."
31
+ },
2
32
  "delete_artifact_confirmation_dialog": {
3
33
  "title": "Supprimer l'artefact ?",
4
34
  "content": "Cela supprimera définitivement « {{ artifactName }} » du magasin d'objets.",
5
35
  "cancel_button": "Annuler",
6
36
  "delete_button": "Supprimer"
7
37
  },
38
+ "delete_component_confirmation_dialog": {
39
+ "title": "Supprimer le composant ?",
40
+ "content": "Cela supprimera définitivement « {{ componentName }} » : un composant n'appartient qu'à cet enregistrement.",
41
+ "cancel_button": "Annuler",
42
+ "delete_button": "Supprimer"
43
+ },
44
+ "statusbar": {
45
+ "breadcrumb_label": "Hiérarchie des enregistrements"
46
+ },
47
+ "tabs": {
48
+ "list": "{{ entity }} - liste",
49
+ "details": "{{ entity }} - détails"
50
+ },
8
51
  "toolbar": {
9
52
  "query_label": "Requête",
10
- "filter_label": "Filtre"
53
+ "query_tooltip": "Interroger la liste avec une expression RSQL",
54
+ "filter_label": "Filtre",
55
+ "filter_tooltip": "Filtrer les lignes chargées par texte",
56
+ "edit_tooltip": "Modifier l'enregistrement sélectionné",
57
+ "new_tooltip": "Créer un nouvel enregistrement",
58
+ "delete_tooltip": "Supprimer les enregistrements sélectionnés"
11
59
  },
12
60
  "pdf_export": {
13
61
  "button": "PDF",
@@ -28,5 +76,8 @@
28
76
  "title": "Éditeur de requêtes avancé",
29
77
  "cancel_button": "Annuler",
30
78
  "apply_button": "Appliquer"
79
+ },
80
+ "embedded_components": {
81
+ "save_owner_first": "Enregistrez cet enregistrement avant d'ajouter {{ entity }} — un composant intégré y est stocké."
31
82
  }
32
83
  }