@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 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`. `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`.
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
- "filter_label": "Filter"
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
- "filter_label": "Filter"
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
- "filter_label": "Filtro"
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
- "filter_label": "Filtre"
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
- "filter_label": "Szűrő"
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",