@nuskin/shipping-address-form 1.7.8-state-dropdown.2 → 1.7.8-state-dropdown.4

package/README.md

@@ -87,11 +87,16 @@ import {
 ```
 
 `AddressLookup` accepts `onAddressSelect`, `country`, `language`, `address`, `readOnlyView`,
-`validationRequestId`, `strings`, `formDefinition`, and `deferFormLookup`. It supports Smarty
-autocomplete and validation for US and international
+`validationRequestId`, `strings`, `formDefinition`, `deferFormLookup`, `showValidFields`, and
+`suppressRequiredFieldsHint`. It supports Smarty autocomplete and validation for US and international
 addresses. `normalizeAddressForm`, `DEFAULT_ADDRESS_FORM`, and `SUPPORTED_COUNTRIES` are exported
 for consumers that need to provide or reuse address form definitions.
 
+`showValidFields` (default `false`) shows a success indicator on fields once they have a value and
+pass validation. `suppressRequiredFieldsHint` (default `false`) hides `AddressLookup`'s own "Fields
+marked with * are required" hint; use this when a parent component (such as `ShippingAddressForm`)
+already renders that hint for the combined form.
+
 ## ShippingAddressForm Props
 
 ### `country`
@@ -217,6 +222,26 @@ When `true`, the wrapper renders in display-only mode:
 
 Readonly mode is intended for displaying an existing address without allowing edits or validation actions.
 
+### `showValidFields`
+
+- Type: `boolean`
+- Default: `false`
+
+When `true`, shipping fields (and the underlying `AddressLookup` fields) show a success indicator
+once a field has a value and passes its own validation. This is passed straight through to
+`AddressLookup` as its own `showValidFields` prop.
+
+### `gateSubmitUntilComplete`
+
+- Type: `boolean`
+- Default: `false`
+
+When `true`, the Save/Continue button is disabled until the address is complete (per
+`addressStatus.completeness`), all shipping-field validation passes, and the phone number (if
+present) is in a valid format. When `false` (default), the button is only disabled while a save is
+in progress; consumers can still attempt Save and rely on the `onAction` payloads described below
+to react to incomplete or invalid state.
+
 ### Address Entry and Validation
 
 Address entry and validation behavior are configured in the address form definition:
@@ -337,6 +362,29 @@ When Smarty autocomplete or validation is unavailable, the wrapper forwards the
 
 Consumers can use this event to apply their own fail-open or fail-closed policy when Smarty is unavailable.
 
+#### Validation-failed payload
+
+Emitted when a Save attempt completes address validation but the address still cannot proceed
+(for example, an unverified address under `validationMode: 'required'`):
+
+```js
+{
+  type: 'validation-failed',
+  address: {
+    address1: '123 Main St'
+  },
+  status: {
+    verification: 'unverified',
+    canProceed: false,
+    needsValidation: true,
+    validationAttempted: true
+  }
+}
+```
+
+Unlike the AddressLookup error payload, this indicates validation ran successfully but the result
+did not meet the configured `validationMode`/`minimumAcceptedLevel` requirements.
+
 ## Form Definition
 
 Shipping form layout is loaded from Contentstack content type:
@@ -400,9 +448,11 @@ Shipping field validation is handled locally.
 - Save is blocked only when email-verify explicitly reports invalid format or invalid domain.
 - Email-verify service failures do not block save.
 - The email-verify base URL resolves to `apis.test.nuskin.com` for local/test-like hosts and `apis.nuskin.com` otherwise.
-- Phone validation uses `isPossiblePhoneNumber()` from `react-phone-number-input`.
+- Phone validation uses `parsePhoneNumberFromString()` from `libphonenumber-js/max` and requires the
+  number to be valid and of type `MOBILE` or `FIXED_LINE_OR_MOBILE` for the selected phone country.
 - Invalid phone numbers show an error message and red field styling.
-- Invalid phone format is currently non-blocking for save.
+- Invalid phone format does not block save by default; set `gateSubmitUntilComplete` to disable
+  Save/Continue until the phone number is valid.
 - When a non-empty phone value is present, `validationStatus.phone` is included in the save callback.
 - If the phone format is invalid, the save callback includes `validationStatus.phone = { valid: false, reason: 'invalid_format' }`.
 - Missing required shipping fields block save.
@@ -460,6 +510,7 @@ The stylesheet also exposes CSS variables for common overrides:
 - `--nssf-border-color`
 - `--nssf-disabled-surface-color`
 - `--nssf-error-color`
+- `--nssf-success-color`
 - `--nssf-primary-color`
 - `--nssf-surface-color`
 - `--nssf-radius`