@processpuzzle/base-entity 1.2.1 → 1.2.2
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 +136 -1
- package/assets/i18n/base_entity/de.json +10 -1
- package/assets/i18n/base_entity/en.json +10 -1
- package/assets/i18n/base_entity/es.json +10 -1
- package/assets/i18n/base_entity/fr.json +10 -1
- package/assets/i18n/base_entity/hu.json +10 -1
- package/fesm2022/processpuzzle-base-entity.mjs +202 -73
- package/fesm2022/processpuzzle-base-entity.mjs.map +1 -1
- package/package.json +1 -1
- package/types/processpuzzle-base-entity.d.ts +64 -3
- package/types/processpuzzle-base-entity.d.ts.map +1 -1
package/README.md
CHANGED
|
@@ -132,7 +132,7 @@ export const TestEntityStore = signalStore(
|
|
|
132
132
|
|
|
133
133
|
### 5. Describe the attributes
|
|
134
134
|
|
|
135
|
-
Each visible field gets a `BaseEntityAttrDescriptor
|
|
135
|
+
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 a related entity (used by `LOOKUP`, `FOREIGN_KEY`, and nested `COMPONENTS`). The descriptor is resolved at runtime through `BASE_ENTITY_FACADE_REGISTRY`.
|
|
136
136
|
|
|
137
137
|
```typescript
|
|
138
138
|
function createTestEntityAttrDescriptors(): AbstractAttrDescriptor[] {
|
|
@@ -211,6 +211,141 @@ export class TestEntityFacade extends BaseEntityFacade<TestEntity> {
|
|
|
211
211
|
|
|
212
212
|
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
213
|
|
|
214
|
+
## Control types
|
|
215
|
+
|
|
216
|
+
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`**.
|
|
217
|
+
|
|
218
|
+
| Type | Renders | Value shape | Required props | Notes |
|
|
219
|
+
| --- | --- | --- | --- | --- |
|
|
220
|
+
| `TEXT_BOX` | `matInput` text field | `string` | `label` | `options.inputType` sets the HTML input type (e.g. `number`). |
|
|
221
|
+
| `TEXTAREA` | `matInput` textarea | `string` | `label` | `lines` sets the row count; `placeholder` the hint. |
|
|
222
|
+
| `CHECKBOX` | `mat-checkbox` | `boolean` | `label` | |
|
|
223
|
+
| `DATE` | `matInput` + `mat-datepicker` | `Date` | `label` | Format is governed by the ambient Material date adapter. |
|
|
224
|
+
| `DROPDOWN` | `mat-select` | selected option's `value` | **`selectables`** | Options come from `selectables` (array or `() => Selectable[]`). |
|
|
225
|
+
| `RADIO` | native radio group | selectable `key` | **`selectables`** | Reactive; stores the `key` of the chosen option. |
|
|
226
|
+
| `TITLE` | `<h2>` section heading (display only) | — | `label` | Renders `label` as a form section title. |
|
|
227
|
+
| `TAGS` | `mat-chip-grid` | `string[]` | `label` | ENTER/COMMA add a chip; chips are editable/removable. |
|
|
228
|
+
| `LABEL` | `<h3>`/`<p>` (display only) | `string` | `label` | `isHeading` renders a heading instead of a paragraph. |
|
|
229
|
+
| `FLEX_BOX` | layout container | — (no control) | uses `FlexboxDescriptor` | Grouping only; recurses into children. See below. |
|
|
230
|
+
| `LOOKUP` | autocomplete over a lookup table | lookup **`key`** (`string`) | **`linkedEntityType`** | Tricky — see below. |
|
|
231
|
+
| `FOREIGN_KEY` | read-only field + Select/link buttons | related entity **`id`** (`string`) | **`linkedEntityType`** | To-one reference; picks via the navigator. |
|
|
232
|
+
| `COMPONENTS` | list of related-entity rows | array of related **ids** | **`linkedEntityType`**, `referenceIdField` | To-many reference. |
|
|
233
|
+
| `ARTIFACT` | file thumbnail/icon + upload/delete | `ArtifactAttr` (or `null`) | `label`, `showThumbnail` | Tricky — see below. |
|
|
234
|
+
| `ADDITIONAL_PROPERTIES` | editable key/value list | `Record<string,string>` | `label` | Free-form string map. |
|
|
235
|
+
|
|
236
|
+
`linkedEntityType` is **mandatory** for `LOOKUP`, `FOREIGN_KEY`, and `COMPONENTS` — it names the related entity, whose descriptor is resolved at runtime through `BASE_ENTITY_FACADE_REGISTRY`; omitting it throws.
|
|
237
|
+
|
|
238
|
+
### FLEX_BOX (layout)
|
|
239
|
+
|
|
240
|
+
`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).
|
|
241
|
+
|
|
242
|
+
### The tricky ones
|
|
243
|
+
|
|
244
|
+
- **`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.
|
|
245
|
+
- **`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.
|
|
246
|
+
- **`COMPONENTS`** 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.
|
|
247
|
+
- **`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.
|
|
248
|
+
|
|
249
|
+
These value-editing controls (`ARTIFACT`, `LOOKUP`, `FOREIGN_KEY`, `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.
|
|
250
|
+
|
|
251
|
+
> **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.
|
|
252
|
+
|
|
253
|
+
## Per-field styling
|
|
254
|
+
|
|
255
|
+
Two descriptor properties give a consumer per-attribute style control, applied via `[ngClass]`:
|
|
256
|
+
|
|
257
|
+
- **`styleClass`** — class(es) on the field **wrapper** (`fieldset` / `mat-form-field` / the radio container).
|
|
258
|
+
- **`labelClass`** — class(es) on the field **label** (`legend` / `mat-label` / checkbox label).
|
|
259
|
+
|
|
260
|
+
There is also a `style` property bound with `[ngStyle]` for one-off inline styles.
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
const expr = new BaseEntityAttrDescriptor('expression', FormControlType.TEXTAREA, 'Expression');
|
|
264
|
+
expr.styleClass = 'monospace full-width';
|
|
265
|
+
expr.labelClass = 'muted';
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
> **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.
|
|
269
|
+
|
|
270
|
+
## Internationalisation
|
|
271
|
+
|
|
272
|
+
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.
|
|
273
|
+
|
|
274
|
+
### 1. Key root is derived from the entity name
|
|
275
|
+
|
|
276
|
+
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).
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
new BaseEntityDescriptor({
|
|
280
|
+
entityName: 'Trunk Data',
|
|
281
|
+
attrDescriptors: createTrunkDataAttrDescriptors(),
|
|
282
|
+
// key root → 'trunk_data' (derived); pass i18nScope only to override
|
|
283
|
+
});
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### 2. Provide the Transloco scope on the route
|
|
287
|
+
|
|
288
|
+
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 `_`.
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
{
|
|
292
|
+
path: 'trunk_data',
|
|
293
|
+
providers: [provideTranslocoScope({ scope: 'trunk_data', alias: 'trunk_data' })],
|
|
294
|
+
// …
|
|
295
|
+
}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### 3. Add the translation files
|
|
299
|
+
|
|
300
|
+
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):
|
|
301
|
+
|
|
302
|
+
- **Entity name** → `<scope>._self` (the reserved `_self` avoids colliding with the attribute keys)
|
|
303
|
+
- **Attribute label** → `<scope>.<attrName>`
|
|
304
|
+
|
|
305
|
+
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.
|
|
306
|
+
|
|
307
|
+
```jsonc
|
|
308
|
+
// assets/i18n/trunk_data/en.json → keys trunk_data._self, trunk_data.key, …
|
|
309
|
+
{
|
|
310
|
+
"_self": "Trunk Data", // entity name in the tabs
|
|
311
|
+
"key": "Reference Key", // attribute labels, keyed by attrName
|
|
312
|
+
"description": "Description",
|
|
313
|
+
"value": "Value"
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
### The library's own strings
|
|
318
|
+
|
|
319
|
+
Everything the library renders that is *not* derived from a descriptor — toolbar labels and tooltips, PDF-export
|
|
320
|
+
and RSQL dialogs, and the list/details tab captions — lives in the `base_entity` scope shipped with the package
|
|
321
|
+
(`assets/i18n/base_entity/<lang>.json`, copied into your build). Provide it once on the route that hosts the
|
|
322
|
+
entity screens:
|
|
323
|
+
|
|
324
|
+
```typescript
|
|
325
|
+
providers: [provideTranslocoScope({ scope: 'base_entity', alias: 'base_entity' })];
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
The tab captions take the resolved entity name as a parameter, so translators control the word order:
|
|
329
|
+
|
|
330
|
+
```jsonc
|
|
331
|
+
"tabs": {
|
|
332
|
+
"list": "{{ entity }} - list", // → "Trunk Data - list"
|
|
333
|
+
"details": "{{ entity }} - details"
|
|
334
|
+
}
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
## Status-bar title
|
|
338
|
+
|
|
339
|
+
The status bar labels the selected entity with the value of one identifying attribute. That attribute
|
|
340
|
+
is `titleKey` on the descriptor, defaulting to the `isLinkToDetails` attribute (the same one
|
|
341
|
+
`componentIdentification()` returns). Set `titleKey` only to point at a different attribute; set the
|
|
342
|
+
`entityTitle` string/function to override the displayed text entirely.
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
new BaseEntityDescriptor({ entityName: 'Order Line', attrDescriptors, titleKey: 'productName' });
|
|
346
|
+
// status bar shows currentEntity().productName
|
|
347
|
+
```
|
|
348
|
+
|
|
214
349
|
## RSQL search
|
|
215
350
|
|
|
216
351
|
The list toolbar carries two independent search inputs:
|
|
@@ -5,9 +5,18 @@
|
|
|
5
5
|
"cancel_button": "Abbrechen",
|
|
6
6
|
"delete_button": "Löschen"
|
|
7
7
|
},
|
|
8
|
+
"tabs": {
|
|
9
|
+
"list": "{{ entity }} - Liste",
|
|
10
|
+
"details": "{{ entity }} - Details"
|
|
11
|
+
},
|
|
8
12
|
"toolbar": {
|
|
9
13
|
"query_label": "Abfrage",
|
|
10
|
-
"
|
|
14
|
+
"query_tooltip": "Liste mit einem RSQL-Ausdruck abfragen",
|
|
15
|
+
"filter_label": "Filter",
|
|
16
|
+
"filter_tooltip": "Geladene Zeilen nach Text filtern",
|
|
17
|
+
"edit_tooltip": "Ausgewählten Datensatz bearbeiten",
|
|
18
|
+
"new_tooltip": "Neuen Datensatz erstellen",
|
|
19
|
+
"delete_tooltip": "Ausgewählte Datensätze löschen"
|
|
11
20
|
},
|
|
12
21
|
"pdf_export": {
|
|
13
22
|
"button": "PDF",
|
|
@@ -5,9 +5,18 @@
|
|
|
5
5
|
"cancel_button": "Cancel",
|
|
6
6
|
"delete_button": "Delete"
|
|
7
7
|
},
|
|
8
|
+
"tabs": {
|
|
9
|
+
"list": "{{ entity }} - list",
|
|
10
|
+
"details": "{{ entity }} - details"
|
|
11
|
+
},
|
|
8
12
|
"toolbar": {
|
|
9
13
|
"query_label": "Query",
|
|
10
|
-
"
|
|
14
|
+
"query_tooltip": "Query the list with an RSQL expression",
|
|
15
|
+
"filter_label": "Filter",
|
|
16
|
+
"filter_tooltip": "Filter the loaded rows by text",
|
|
17
|
+
"edit_tooltip": "Edit the selected record",
|
|
18
|
+
"new_tooltip": "Create a new record",
|
|
19
|
+
"delete_tooltip": "Delete the selected records"
|
|
11
20
|
},
|
|
12
21
|
"pdf_export": {
|
|
13
22
|
"button": "PDF",
|
|
@@ -5,9 +5,18 @@
|
|
|
5
5
|
"cancel_button": "Cancelar",
|
|
6
6
|
"delete_button": "Eliminar"
|
|
7
7
|
},
|
|
8
|
+
"tabs": {
|
|
9
|
+
"list": "{{ entity }} - lista",
|
|
10
|
+
"details": "{{ entity }} - detalles"
|
|
11
|
+
},
|
|
8
12
|
"toolbar": {
|
|
9
13
|
"query_label": "Consulta",
|
|
10
|
-
"
|
|
14
|
+
"query_tooltip": "Consultar la lista con una expresión RSQL",
|
|
15
|
+
"filter_label": "Filtro",
|
|
16
|
+
"filter_tooltip": "Filtrar las filas cargadas por texto",
|
|
17
|
+
"edit_tooltip": "Editar el registro seleccionado",
|
|
18
|
+
"new_tooltip": "Crear un nuevo registro",
|
|
19
|
+
"delete_tooltip": "Eliminar los registros seleccionados"
|
|
11
20
|
},
|
|
12
21
|
"pdf_export": {
|
|
13
22
|
"button": "PDF",
|
|
@@ -5,9 +5,18 @@
|
|
|
5
5
|
"cancel_button": "Annuler",
|
|
6
6
|
"delete_button": "Supprimer"
|
|
7
7
|
},
|
|
8
|
+
"tabs": {
|
|
9
|
+
"list": "{{ entity }} - liste",
|
|
10
|
+
"details": "{{ entity }} - détails"
|
|
11
|
+
},
|
|
8
12
|
"toolbar": {
|
|
9
13
|
"query_label": "Requête",
|
|
10
|
-
"
|
|
14
|
+
"query_tooltip": "Interroger la liste avec une expression RSQL",
|
|
15
|
+
"filter_label": "Filtre",
|
|
16
|
+
"filter_tooltip": "Filtrer les lignes chargées par texte",
|
|
17
|
+
"edit_tooltip": "Modifier l'enregistrement sélectionné",
|
|
18
|
+
"new_tooltip": "Créer un nouvel enregistrement",
|
|
19
|
+
"delete_tooltip": "Supprimer les enregistrements sélectionnés"
|
|
11
20
|
},
|
|
12
21
|
"pdf_export": {
|
|
13
22
|
"button": "PDF",
|
|
@@ -5,9 +5,18 @@
|
|
|
5
5
|
"cancel_button": "Mégse",
|
|
6
6
|
"delete_button": "Törlés"
|
|
7
7
|
},
|
|
8
|
+
"tabs": {
|
|
9
|
+
"list": "{{ entity }} - lista",
|
|
10
|
+
"details": "{{ entity }} - részletek"
|
|
11
|
+
},
|
|
8
12
|
"toolbar": {
|
|
9
13
|
"query_label": "Lekérdezés",
|
|
10
|
-
"
|
|
14
|
+
"query_tooltip": "Lista lekérdezése RSQL kifejezéssel",
|
|
15
|
+
"filter_label": "Szűrő",
|
|
16
|
+
"filter_tooltip": "Betöltött sorok szűrése szöveg alapján",
|
|
17
|
+
"edit_tooltip": "Kijelölt rekord szerkesztése",
|
|
18
|
+
"new_tooltip": "Új rekord létrehozása",
|
|
19
|
+
"delete_tooltip": "Kijelölt rekordok törlése"
|
|
11
20
|
},
|
|
12
21
|
"pdf_export": {
|
|
13
22
|
"button": "PDF",
|