@ng-simplicity/forms-core 1.1.3 → 1.1.5

package/README.md

@@ -15,7 +15,7 @@ This core package is extended by styling integration packages that provide prebu
 
 | Package | Package version | Angular support |
 |---|---:|---|
-| `@ng-simplicity/forms-core` | `1.1.3` | `17.x`–`22.x` |
+| `@ng-simplicity/forms-core` | `1.1.5` | `17.x`–`22.x` |
 
 ---
 
@@ -46,7 +46,8 @@ Each `registerAll…` helper also registers the core structural components, so i
 ### 1. The Public Boundary: `NgsFormsService`
 - Injected by the user's component page.
 - Exposes form values and statuses through Signals and observables (e.g. `formValue$`, `dirty`, `isValid`).
-- Provides entry methods like `setFormConfig(config)` and `patchValue(data)`.
+- Provides entry methods like `setFormConfig(config)`, `patchValue(data)` and `setServerErrorMessages(errors)`.
+- `patchValue(data)` can be called straight after `setFormConfig()`: it keeps the patch and re-applies it as controls render, including fields that the patched values reveal through `visible$`, until the form settles. Form arrays need enough rows (`initialItemCount`).
 - Implements a retry loading mechanism in case child elements compile asynchronously.
 
 ### 2. The Internal Coordinator: `NgsFormsInternalService`
@@ -217,6 +218,18 @@ Each form control component that extends `NgsFormsFormItemWithVisibleAndValidato
    }
    ```
 3. **Displaying Errors**: Within your custom component template, bind your error display element to the `errorMessage` property inherited from the base class. The core engine dynamically updates `errorMessage` based on whether the control is invalid, touched, dirty, or if the form has been submitted.
+4. **Server Errors**: Pass the server's errors to `NgsFormsService.setServerErrorMessages()` in the same shape as the form value. Each leaf is a key looked up in that field's `errorMessageMap` (a key with no entry is shown as text), and form array rows are matched by index. Each error clears when its field changes, and the call returns the paths that matched no control. `constructServerErrorMessageObject()` builds the object from a list of `{ jsonPath, validator }` pairs:
+   ```typescript
+   errorMessageMap: { taken: 'User Name Not Available' }
+
+   this.formsService.setServerErrorMessages({ registration: { userName: 'taken', contacts: [{}, {}, { phone: 'invalidPhone' }] } });
+
+   // Same thing from a flat list:
+   this.formsService.setServerErrorMessages(constructServerErrorMessageObject([
+     { jsonPath: 'registration.userName', validator: 'taken' },
+     { jsonPath: 'registration.contacts[2].phone', validator: 'invalidPhone' },
+   ]));
+   ```
 
 ---
 
@@ -397,10 +410,17 @@ import { NgsFormsFormArrayRemoveItemComponent } from '@ng-simplicity/forms-core'
 const removeContactBtn = NgsFormsFormArrayRemoveItemComponent.create({
   buttonText: 'Delete',
   buttonClass: 'btn btn-danger',
-  buttonIcon: 'trash-icon'
+  buttonIcon: 'trash-icon',
+  // Optional accessible name. Defaults to `${buttonText} item ${index + 1}`, for example "Delete item 2".
+  ariaLabel: (index) => `Delete contact ${index + 1}`,
 });
 ```
 
+The button always removes its own row, even after earlier rows have been removed. When the removed row held the focus, focus moves to the Remove button of the row that takes its place. Custom components inside a row can inject `NGS_FORMS_ARRAY_ROW` (the row's `UntypedFormGroup`) and use `formArray.controls.indexOf(row)` to find the row's current index; `NGS_FORMS_ITEM_INDEX` is the index the row had when it was created.
+
+```typescript
+```
+
 ### 5. Section (`section`)
 A visual layout grouping with a title and subtitle.
 - **Component**: `NgsFormsFormSectionComponent`
@@ -413,6 +433,7 @@ import { NgsFormsFormSectionComponent } from '@ng-simplicity/forms-core';
 const personalSection = NgsFormsFormSectionComponent.create({
   title: 'Personal Information',
   titleClass: 'custom-title-class', // Optional, defaults to 'h3'
+  headingLevel: 2, // Optional heading level announced by screen readers, defaults to 3
   subtitle: 'Tell us a bit about yourself',
   subtitleClass: 'custom-subtitle-class', // Optional, defaults to 'lead'
   items: [