ng-hub-ui-forms 21.0.0 → 22.1.1

package/README.md

@@ -26,13 +26,16 @@ This library is part of the **ng-hub-ui** ecosystem:
 - [**ng-hub-ui-breadcrumbs**](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
 - [**ng-hub-ui-calendar**](https://www.npmjs.com/package/ng-hub-ui-calendar)
 - [**ng-hub-ui-dropdown**](https://www.npmjs.com/package/ng-hub-ui-dropdown)
+- [**ng-hub-ui-ds**](https://www.npmjs.com/package/ng-hub-ui-ds)
 - [**ng-hub-ui-forms**](https://www.npmjs.com/package/ng-hub-ui-forms) ← You are here
 - [**ng-hub-ui-history**](https://www.npmjs.com/package/ng-hub-ui-history)
+- [**ng-hub-ui-milestones**](https://www.npmjs.com/package/ng-hub-ui-milestones)
 - [**ng-hub-ui-modal**](https://www.npmjs.com/package/ng-hub-ui-modal)
 - [**ng-hub-ui-nav**](https://www.npmjs.com/package/ng-hub-ui-nav)
 - [**ng-hub-ui-paginable**](https://www.npmjs.com/package/ng-hub-ui-paginable)
 - [**ng-hub-ui-panels**](https://www.npmjs.com/package/ng-hub-ui-panels)
 - [**ng-hub-ui-portal**](https://www.npmjs.com/package/ng-hub-ui-portal)
+- [**ng-hub-ui-skeleton**](https://www.npmjs.com/package/ng-hub-ui-skeleton)
 - [**ng-hub-ui-sortable**](https://www.npmjs.com/package/ng-hub-ui-sortable)
 - [**ng-hub-ui-stepper**](https://www.npmjs.com/package/ng-hub-ui-stepper)
 - [**ng-hub-ui-utils**](https://www.npmjs.com/package/ng-hub-ui-utils)
@@ -88,7 +91,7 @@ mode — no Bootstrap dependency.
 
 ## 🎯 Features
 
-- **Fields** — `hub-input` (text/number/email/password/color/switch/checkbox/counter, with input-group addons & masks), `hub-otp`, `hub-textarea` (+ `hubAutoresize`), `hub-slider`, `hub-select` (dropdown / buttons / checkbox / radio formats, grouping, typeahead, custom templates), `hub-datepicker` (single & range, keyboard nav, i18n).
+- **Fields** — `hub-input` (text/number/email/password/color/switch/checkbox/counter, with input-group addons & masks), `hub-otp-input`, `hub-textarea` (+ `hubAutoresize`), `hub-slider`, `hub-select` (dropdown / buttons / checkbox / radio formats, grouping, typeahead, custom templates), `hub-datepicker` (single & range, keyboard nav, i18n).
 - **Automatic error display** — bind a field and its control errors render below it; `hub-fieldset`, `form[hubForm]` and `hub-legend` surface group- and form-level (cross-field) errors the same way, with zero wiring.
 - **Containers** — `hub-fieldset` / `form[hubForm]` group fields and show their group errors; `hub-legend` renders an accessible legend.
 - **Configurable** — `provideHubForms({ … })` sets the invalid-feedback templates, datepicker locale/labels and more, app-wide or per instance.
@@ -182,6 +185,22 @@ form = new FormGroup(
 On submit, each invalid field shows its error and the cross-field `hubAreEqual`
 error is surfaced by the fieldset/form — no manual error markup anywhere.
 
+### Validation states (invalid is automatic, valid is opt-in)
+
+The **invalid** state is always automatic: a touched, invalid field shows its
+error styling and message with no configuration. The **valid / success** state is
+strictly **opt-in** — success is *never* shown automatically. Enable it per field
+with the `showValid` input, and optionally add a `validFeedback` message that
+renders below the control once the field is touched and valid:
+
+```html
+<hub-input formControlName="username" label="Username" required [showValid]="true" validFeedback="Looks good!" />
+```
+
+To turn the success state on for every field at once, set it globally — see
+[Configuration](#-configuration). A per-field `showValid` always overrides the
+global default.
+
 ---
 
 ## 🛠️ Configuration
@@ -194,12 +213,18 @@ import { provideHubForms } from 'ng-hub-ui-forms';
 bootstrapApplication(AppComponent, {
 	providers: [
 		provideHubForms({
+			showValid: true,
 			datepicker: { firstDayOfWeek: 1, displayFormat: 'dd/MM/yyyy' }
 		})
 	]
 });
 ```
 
+`showValid` (default `false`) turns the opt-in valid/success state on for every
+field once it is touched and valid. The invalid state is unaffected — it is always
+automatic; only success is gated behind this flag. A per-field `showValid` input
+overrides the global default.
+
 ---
 
 ## 🎨 Styling
@@ -219,6 +244,18 @@ hub-select {
 }
 ```
 
+The opt-in valid/success state is themed through four tokens (chained to the
+`--hub-sys-color-success` family by default):
+
+```css
+hub-input {
+	--hub-form-valid-color: #198754;
+	--hub-form-valid-border-color: #198754;
+	--hub-form-valid-focus-ring-color: rgba(25, 135, 84, 0.25);
+	--hub-form-valid-feedback-color: #198754;
+}
+```
+
 ---
 
 ## ✨ Signal Forms (opt-in)