ng-hub-ui-forms 21.0.0 → 22.1.2

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)
@@ -81,14 +84,15 @@ The required `email` field reveals its error automatically on submit — no manu
 `ng-hub-ui-forms` unifies a set of accessible form fields behind one contract:
 bind them with **Reactive Forms** and the matching validation errors appear
 **automatically** at the control, group and form level. Fields are standalone,
-`OnPush` and signal-native; the select is a maintained fork of ng-select; the
+`OnPush` and signal-native; the select is a maintained fork of
+[ng-select](https://github.com/ng-select/ng-select) (see [Credits](#-credits)); the
 datepicker is built from scratch on native `Date` and the Angular CDK overlay.
 Everything is themed through canonical `--hub-*` CSS variables with runtime dark
 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 +186,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 +214,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 +245,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)
@@ -247,6 +285,14 @@ See [CHANGELOG.md](./CHANGELOG.md).
 
 ---
 
+## 🙏 Credits
+
+`hub-select` is a maintained **fork of [ng-select](https://github.com/ng-select/ng-select)** by the ng-select contributors. The upstream `src/ng-select` sources are vendored in place and re-themed with `--hub-*` tokens — pinned to upstream **`v23.0.1`** (tracked in [`src/lib/select/UPSTREAM`](./src/lib/select/UPSTREAM); deviations documented in [`src/lib/select/PATCHES.md`](./src/lib/select/PATCHES.md)). ng-select is distributed under the [MIT License](https://github.com/ng-select/ng-select/blob/master/LICENSE.md), and the original copyright notices are retained in the vendored files.
+
+The datepicker, inputs and validation layer are original to `ng-hub-ui-forms`.
+
+---
+
 ## 📄 License
 
 MIT © [Carlos Morcillo](https://www.carlosmorcillo.com)