@vtex/faststore 0.0.10 → 0.0.11

package/dist/matter/shipping-address/shipping-address.js

@@ -1,17 +1,23 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
+import { useStorefrontFormatters } from "../../sdk/format/client.js";
+import { useMessageFormatter } from "../../sdk/i18n/use-message-formatter.js";
 import { Field, FieldBinding, FieldsetFieldContext, readBaseline, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset } from "../../particles/field/field.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
+import { formatErrorCode } from "../../sdk/i18n/format-error-code.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
-import { resolveAuthoredCopy } from "../../utils/resolve-authored-copy.js";
-import { useFormRegistry } from "../../particles/form/form.js";
 import { useEntityDataResolved } from "../../sdk/data/entity-resolution-context.js";
 import { useReactiveDataSettled } from "../../sdk/data/use-reactive-data-settled.js";
+import { countryDisplayName } from "../../sdk/address/country-display.js";
+import { useFormRegistry } from "../../particles/form/form.js";
 import { Fieldset } from "../../particles/fieldset/fieldset.js";
+import { normalizeAddressField, pickActiveTextFields } from "./address-payload.js";
+import { LIBRARY_COUNTRIES, useLibraryCountryDescriptors } from "./library-country-descriptors.js";
 import { getAvailableCountries, getCountryDescriptor } from "./country-descriptors.js";
 import { FieldSelect } from "../../particles/select/field-select.js";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useFormContext, useWatch } from "react-hook-form";
 //#region src/matter/shipping-address/shipping-address.tsx
@@ -94,15 +100,23 @@ const FIELD_AUTOCOMPLETE = {
 	state: "address-level1"
 };
 /**
-* Merges the descriptor's own `rule` under a generated `required`, which is this fieldset's whole
-* declaration of the baseline. The blank check it used to hand-write alongside lives in
-* `resolveRequiredness` now, installed for every bound control rather than only for this one.
+* Words the descriptor's structural `rule` with the form's messages, under a generated `required`, which is
+* this fieldset's whole declaration of the baseline. The blank check it used to hand-write alongside lives
+* in `resolveRequiredness` now, installed for every bound control rather than only for this one.
 */
-function buildRule(field, label, requiredSuffix) {
-	if (!field.required) return field.rule;
+function textOf(value) {
+	return typeof value === "string" ? value : "";
+}
+function buildRule(field, requiredMessage, invalidMessage) {
+	const pattern = field.rule?.pattern;
+	const validate = field.rule?.validate;
 	return {
-		...field.rule,
-		required: `${label} ${requiredSuffix}`
+		pattern: pattern ? {
+			value: pattern,
+			message: invalidMessage
+		} : void 0,
+		validate: validate ? (value) => validate(textOf(value)) || invalidMessage || false : void 0,
+		required: field.required ? requiredMessage : void 0
 	};
 }
 /** Keeps only the AddressDraft keys `values` actually defines — a field no control composed is absent, not `undefined`. */
@@ -114,6 +128,285 @@ function pickDefinedAddressFields(values) {
 	}
 	return result;
 }
+const ShippingAddressFieldsetContent = defineContentType({
+	id: "shipping-address-fieldset",
+	title: "Shipping Address Fieldset",
+	description: "Announcements and accessible name of the delivery address group, and its required-field message.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			loadingLabel: {
+				type: "string",
+				title: "Loading announcement",
+				description: "Announced politely while the address resolves.",
+				format: "icu-message",
+				messageSource: "Loading your delivery address"
+			},
+			loadedLabel: {
+				type: "string",
+				title: "Loaded announcement",
+				description: "Announced politely once the fields mount.",
+				format: "icu-message",
+				messageSource: "Your delivery address is ready"
+			},
+			groupLabel: {
+				type: "string",
+				title: "Accessible group name",
+				description: "A composed FieldsetLegend wins over it.",
+				format: "icu-message",
+				messageSource: "Your delivery address",
+				messageOptional: true
+			},
+			requiredMessage: {
+				type: "string",
+				title: "Required field message",
+				description: "Shown under a required field left blank; label is that field's label.",
+				format: "icu-message",
+				messageSource: "{label} is required",
+				messageArguments: {
+					type: "object",
+					properties: { label: { type: "string" } }
+				},
+				messageExample: { label: "recipient name" }
+			},
+			missingRecipientNameMessage: {
+				type: "string",
+				title: "Missing recipient name message",
+				description: "Shown by FormError when the server refuses a blank recipient name.",
+				format: "icu-message",
+				messageSource: "Enter the recipient's name."
+			},
+			invalidPostalCodeMessage: {
+				type: "string",
+				title: "Invalid postal code message",
+				description: "Shown by FormError when the server refuses the postal code.",
+				format: "icu-message",
+				messageSource: "Enter a valid postal code."
+			},
+			invalidAddressMessage: {
+				type: "string",
+				title: "Invalid address message",
+				description: "Shown by FormError when the server refuses the address.",
+				format: "icu-message",
+				messageSource: "Check the address and try again."
+			},
+			genericErrorMessage: {
+				type: "string",
+				title: "Generic error message",
+				description: "Shown by FormError for a network failure or a refusal the shopper cannot fix.",
+				format: "icu-message",
+				messageSource: "Unable to save your delivery address. Please try again."
+			}
+		}
+	}
+});
+/**
+* The message for each refusal of the address write: every `ShippingAddressUpdateErrorCode` plus the
+* client-minted transport failure. `dispatch` hands `FormError` this copy, never the server's English
+* `message`: a code this map does not know shows genericErrorMessage.
+*/
+const SHIPPING_ADDRESS_FIELDSET_ERROR_FIELDS = {
+	MISSING_RECIPIENT_NAME: "missingRecipientNameMessage",
+	INVALID_POSTAL_CODE: "invalidPostalCodeMessage",
+	INVALID_ADDRESS: "invalidAddressMessage",
+	MISSING_CART_CONTEXT: "genericErrorMessage",
+	CART_NOT_FOUND: "genericErrorMessage",
+	INVALID_SAVED_ADDRESS_ID: "genericErrorMessage",
+	INVALID_COUNTRY_CODE: "genericErrorMessage",
+	NETWORK_ERROR: "genericErrorMessage"
+};
+function wordShippingAddressError(error, { format }) {
+	return {
+		code: error.code,
+		message: formatErrorCode(ShippingAddressFieldsetContent, SHIPPING_ADDRESS_FIELDSET_ERROR_FIELDS, error, format, "genericErrorMessage")
+	};
+}
+const ShippingAddressRecipientNameContent = defineContentType({
+	id: "shipping-address-recipient-name",
+	title: "Shipping Address Recipient Name",
+	description: "Label of the recipient name field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "recipient name"
+		} }
+	}
+});
+const ShippingAddressStreetContent = defineContentType({
+	id: "shipping-address-street",
+	title: "Shipping Address Street",
+	description: "Label of the street field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "street"
+		} }
+	}
+});
+const ShippingAddressNumberContent = defineContentType({
+	id: "shipping-address-number",
+	title: "Shipping Address Number",
+	description: "Label of the number field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "number"
+		} }
+	}
+});
+const ShippingAddressComplementContent = defineContentType({
+	id: "shipping-address-complement",
+	title: "Shipping Address Complement",
+	description: "Label of the complement field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "apartment, suite, etc. (optional)"
+		} }
+	}
+});
+const ShippingAddressNeighborhoodContent = defineContentType({
+	id: "shipping-address-neighborhood",
+	title: "Shipping Address Neighborhood",
+	description: "Label of the neighborhood field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "neighborhood"
+		} }
+	}
+});
+const ShippingAddressCityContent = defineContentType({
+	id: "shipping-address-city",
+	title: "Shipping Address City",
+	description: "Label of the city field of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "city"
+		} }
+	}
+});
+const ShippingAddressStateContent = defineContentType({
+	id: "shipping-address-state",
+	title: "Shipping Address State",
+	description: "Label of the state field of the delivery address, worded per country.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			description: "country is the active country (ISO 3166-1 alpha-3).",
+			format: "icu-message",
+			messageSource: "{country, select, CAN {province} other {state}}",
+			messageArguments: {
+				type: "object",
+				properties: { country: {
+					type: "string",
+					enum: [
+						"BRA",
+						"USA",
+						"CAN",
+						"MEX"
+					]
+				} }
+			},
+			messageExample: { country: "CAN" }
+		} }
+	}
+});
+const ShippingAddressPostalCodeContent = defineContentType({
+	id: "shipping-address-postal-code",
+	title: "Shipping Address Postal Code",
+	description: "Label of the postal code field of the delivery address and its format message, worded per country.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			label: {
+				type: "string",
+				title: "Field label",
+				description: "country is the active country (ISO 3166-1 alpha-3).",
+				format: "icu-message",
+				messageSource: "{country, select, USA {zip code} other {postal code}}",
+				messageArguments: {
+					type: "object",
+					properties: { country: {
+						type: "string",
+						enum: [
+							"BRA",
+							"USA",
+							"CAN",
+							"MEX"
+						]
+					} }
+				},
+				messageExample: { country: "USA" }
+			},
+			invalidMessage: {
+				type: "string",
+				title: "Invalid postal code message",
+				description: "Shown under a postal code not in the active country's format. Never contains the typed value.",
+				format: "icu-message",
+				messageSource: "{country, select, USA {invalid zip code} other {invalid postal code}}",
+				messageArguments: {
+					type: "object",
+					properties: { country: {
+						type: "string",
+						enum: [
+							"BRA",
+							"USA",
+							"CAN",
+							"MEX"
+						]
+					} }
+				},
+				messageExample: { country: "USA" }
+			}
+		}
+	}
+});
+const ShippingAddressCountryContent = defineContentType({
+	id: "shipping-address-country",
+	title: "Shipping Address Country",
+	description: "Label of the country selector of the delivery address.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { label: {
+			type: "string",
+			title: "Field label",
+			format: "icu-message",
+			messageSource: "country"
+		} }
+	}
+});
 const ShippingAddressFieldsetDefinition = defineComponent({
 	name: "ShippingAddressFieldset",
 	importPath: "@vtex/faststore/components",
@@ -124,6 +417,7 @@ const ShippingAddressFieldsetDefinition = defineComponent({
 	actions: { shipping: ["setAddress"] },
 	requiresContext: "form",
 	providesContext: "shipping-address",
+	content: ShippingAddressFieldsetContent,
 	editor: {
 		label: "Shipping Address Fieldset",
 		category: "commerce"
@@ -138,217 +432,160 @@ const ShippingAddressFieldsetDefinition = defineComponent({
 			type: "number",
 			default: 9,
 			label: "Skeleton rows"
-		},
-		loadingLabel: {
-			type: "string",
-			default: "Loading your delivery address",
-			label: "Loading announcement"
-		},
-		loadedLabel: {
-			type: "string",
-			default: "Your delivery address is ready",
-			label: "Loaded announcement"
-		},
-		groupLabel: {
-			type: "string",
-			default: "Your delivery address",
-			label: "Accessible group name"
 		}
 	},
-	guideline: "Composable delivery-address entity: registers under \"shippingAddress\" with the enclosing FormRoot and dispatches shipping.setAddress only when the shopper changed something. Compose the nine ShippingAddress*Control parts inside it; place FormSubmit/FormEnterSubmit/FormError as siblings of the fieldset, not inside it — this fieldset renders no submit or error part of its own. The Controls mount only once the address has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of Controls composed, or the form jumps by the difference. Style the announcement sr-only. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it. See shipping-address.md."
+	guideline: "Composable delivery-address entity: registers under \"shippingAddress\" with the enclosing FormRoot and dispatches shipping.setAddress only when the shopper changed something. Compose the nine ShippingAddress*Control parts inside it; place FormSubmit/FormEnterSubmit/FormError as siblings of the fieldset, not inside it — this fieldset renders no submit or error part of its own. The Controls mount only once the address has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of Controls composed, or the form jumps by the difference. Style the announcement sr-only; its two messages are the $content fields loadingLabel and loadedLabel. The $content field groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it. A required field left blank shows the $content field requiredMessage, whose label argument is the label of that field. See shipping-address.md."
 });
-const ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX = "Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, Field.Control and Field.Error as children, in any order, to reorder or extend the anatomy; a childless composition keeps the default label-control-error order.";
+const ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX = "Its label is the $content field label. Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, Field.Control and Field.Error as children, in any order, to reorder or extend the anatomy; a childless composition keeps the default label-control-error order.";
 const ShippingAddressRecipientNameControlDefinition = defineComponent({
 	name: "ShippingAddressRecipientNameControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressRecipientNameControl,
+	content: ShippingAddressRecipientNameContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Recipient Name Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `Recipient-name input field; required for submit. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressStreetControlDefinition = defineComponent({
 	name: "ShippingAddressStreetControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressStreetControl,
+	content: ShippingAddressStreetContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Street Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `Street name input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressNumberControlDefinition = defineComponent({
 	name: "ShippingAddressNumberControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressNumberControl,
+	content: ShippingAddressNumberContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Number Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `Street number input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressCityControlDefinition = defineComponent({
 	name: "ShippingAddressCityControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressCityControl,
+	content: ShippingAddressCityContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "City Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `City name input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressStateControlDefinition = defineComponent({
 	name: "ShippingAddressStateControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressStateControl,
+	content: ShippingAddressStateContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "State Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
-	guideline: `State/province input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
+	guideline: `State/province input field; its label takes the active country as the country select argument. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressPostalCodeControlDefinition = defineComponent({
 	name: "ShippingAddressPostalCodeControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressPostalCodeControl,
+	content: ShippingAddressPostalCodeContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Postal Code Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
-	guideline: `Postal code input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
+	guideline: `Postal code input field; its label and invalidMessage take the active country as the country select argument. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressComplementControlDefinition = defineComponent({
 	name: "ShippingAddressComplementControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressComplementControl,
+	content: ShippingAddressComplementContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Complement Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `Complement (apartment, suite, etc.) input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressNeighborhoodControlDefinition = defineComponent({
 	name: "ShippingAddressNeighborhoodControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressNeighborhoodControl,
+	content: ShippingAddressNeighborhoodContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Neighborhood Control",
 		category: "action"
 	},
-	schema: {
-		label: {
-			type: "string",
-			label: "Field label"
-		},
-		placeholder: {
-			type: "string",
-			label: "Placeholder"
-		}
-	},
+	schema: { placeholder: {
+		type: "string",
+		label: "Placeholder"
+	} },
 	guideline: `Neighborhood (bairro) input field; shown only for countries that have this field (BR in v1). ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressCountryControlDefinition = defineComponent({
 	name: "ShippingAddressCountryControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressCountryControl,
+	content: ShippingAddressCountryContent,
 	requiresContext: "shipping-address",
 	providesContext: "field",
 	editor: {
 		label: "Country Control",
 		category: "action"
 	},
-	schema: { label: {
-		type: "string",
-		label: "Field label"
-	} },
-	guideline: "Country selector; lists only countries with an implemented descriptor. Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, FieldSelect.Root and Field.Error as children, in any order; a childless composition keeps the default label-select-error order."
+	schema: {},
+	guideline: "Country selector; lists only countries with an implemented descriptor, each named in the store locale. Its label is the $content field label. Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, FieldSelect.Root and Field.Error as children, in any order; a childless composition keeps the default label-select-error order."
 });
 /** The message a constrained rule member carries; a bare value (or a bare `RegExp`) carries none. */
 function messageOf(constraint) {
@@ -384,10 +621,12 @@ function messagesOf(rule) {
 function useRewordErroredField(name, rule) {
 	const { getFieldState, trigger } = useFormContext();
 	const copy = messagesOf(rule).join("\n");
+	const validate = rule?.validate;
 	useEffect(() => {
 		if (getFieldState(name).error) trigger(name);
 	}, [
 		copy,
+		validate,
 		name,
 		getFieldState,
 		trigger
@@ -420,14 +659,21 @@ function useRewordErroredField(name, rule) {
 * polite live region that announces `loadingLabel` and then `loadedLabel`. Style the region
 * `sr-only` — it is text meant for a screen reader, not for the page.
 */
-function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPPING_ADDRESS_SKELETON_ROWS, loadingLabel = "Loading your delivery address", loadedLabel = "Your delivery address is ready", groupLabel = "Your delivery address", className, children, $data: $dataProp, $actions: $actionsProp }) {
+function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPPING_ADDRESS_SKELETON_ROWS, className, children, $data: $dataProp, $actions: $actionsProp, $content }) {
 	const { registerFieldset } = useFormRegistry();
 	useNoAncestorFieldset("ShippingAddressFieldset");
 	const $data = useDataOverride($dataProp);
 	const $actions = useActionsOverride($actionsProp);
+	const messages = useMessageFormatter(ShippingAddressFieldsetContent, $content);
+	const { format } = messages;
+	const messagesRef = useRef(messages);
+	useEffect(() => {
+		messagesRef.current = messages;
+	}, [messages]);
+	const { displayName } = useStorefrontFormatters();
 	const settled = useReactiveDataSettled();
 	const sliceResolved = useEntityDataResolved();
-	const resolved = settled && sliceResolved && $data !== void 0;
+	const { loaded: loadedLibraryCountries, settled: libraryCountriesSettled } = useLibraryCountryDescriptors();
 	const currentAddress = $data?.shipping?.address;
 	const clientProfile = $data?.clientProfile;
 	const joinedProfileName = [clientProfile?.firstName, clientProfile?.lastName].filter(Boolean).join(" ");
@@ -451,27 +697,40 @@ function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPP
 		defaultValue: seed.country
 	});
 	const activeCountry = typeof watchedCountry === "string" && watchedCountry || seed.country;
-	const descriptor = getCountryDescriptor(activeCountry);
-	const requiredSuffix = descriptor?.requiredSuffix ?? "";
+	const descriptor = LIBRARY_COUNTRIES.includes(activeCountry) && !loadedLibraryCountries.includes(activeCountry) ? void 0 : getCountryDescriptor(activeCountry);
+	const resolved = settled && sliceResolved && $data !== void 0 && (descriptor !== void 0 || libraryCountriesSettled);
 	const fieldFor = useCallback((key) => descriptor?.fields.find((f) => f.name === key), [descriptor]);
 	const seedFor = useCallback((key) => seed[key], [seed]);
-	const ruleFor = useCallback((key, label) => {
+	const ruleFor = useCallback((key, label, invalidMessage) => {
 		const field = fieldFor(key);
-		return field ? buildRule(field, label, requiredSuffix) : void 0;
-	}, [fieldFor, requiredSuffix]);
-	const countryOptions = useMemo(() => getAvailableCountries().map((iso) => ({
-		value: iso,
-		label: getCountryDescriptor(iso)?.label ?? iso
-	})), []);
+		if (!field) return void 0;
+		return buildRule(field, field.required ? format("requiredMessage", { label }) : "", invalidMessage);
+	}, [fieldFor, format]);
+	const countryOptions = useMemo(() => {
+		const libraryCountries = new Set(LIBRARY_COUNTRIES);
+		const loaded = new Set(loadedLibraryCountries);
+		const options = [];
+		for (const iso of getAvailableCountries()) {
+			if (libraryCountries.has(iso) && !loaded.has(iso)) continue;
+			options.push({
+				value: iso,
+				label: countryDisplayName(iso, displayName) ?? iso
+			});
+		}
+		return options;
+	}, [loadedLibraryCountries, displayName]);
+	const country = activeCountry;
 	const fieldsetContextValue = useMemo(() => ({
 		namespace: SHIPPING_ADDRESS_NAMESPACE,
 		descriptor,
+		country,
 		fieldFor,
 		seedFor,
 		ruleFor,
 		countryOptions
 	}), [
 		descriptor,
+		country,
 		fieldFor,
 		seedFor,
 		ruleFor,
@@ -489,18 +748,13 @@ function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPP
 		return {
 			country,
 			...isActive("recipientName") ? { recipientName: String(merged.recipientName ?? "").trim() } : {},
-			...isActive("postalCode") ? { postalCode: merged.postalCode } : {},
-			...isActive("street") ? { street: merged.street } : {},
-			...isActive("number") ? { number: merged.number } : {},
-			...isActive("complement") ? { complement: merged.complement } : {},
-			...isActive("neighborhood") ? { neighborhood: merged.neighborhood } : {},
-			...isActive("city") ? { city: merged.city } : {},
-			...isActive("state") ? { state: merged.state } : {}
+			...isActive("postalCode") ? { postalCode: normalizeAddressField(active?.fields ?? [], "postalCode", merged.postalCode) } : {},
+			...pickActiveTextFields(active?.fields ?? [], merged)
 		};
 	}, [seed]);
 	const dispatch = useCallback(async (payload) => {
 		if (!$actions?.shipping?.setAddress) throw new Error("ShippingAddressFieldset requires $actions.shipping.setAddress.");
-		return $actions.shipping.setAddress(payload);
+		return (await $actions.shipping.setAddress(payload)).map((error) => wordShippingAddressError(error, messagesRef.current));
 	}, [$actions]);
 	const registration = useMemo(() => ({
 		namespace: SHIPPING_ADDRESS_NAMESPACE,
@@ -515,14 +769,15 @@ function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPP
 	]);
 	useEffect(() => registerFieldset(registration), [registerFieldset, registration]);
 	const [announcement, setAnnouncement] = useState("");
-	const announced = resolved ? loadedLabel : loadingLabel;
+	const announced = format(resolved ? "loadedLabel" : "loadingLabel");
+	const groupLabel = format("groupLabel");
 	useEffect(() => {
 		setAnnouncement(announced);
 	}, [announced]);
 	return /* @__PURE__ */ jsxs(Fieldset.Root, {
 		className,
 		"aria-busy": resolved ? void 0 : true,
-		...groupLabel?.trim() ? { "aria-label": groupLabel } : {},
+		...groupLabel.trim() ? { "aria-label": groupLabel } : {},
 		"data-fs-shipping-address-fieldset": "",
 		...resolved ? {} : { "data-fs-shipping-address-fieldset-pending": "" },
 		children: [/* @__PURE__ */ jsx(ShippingAddressFieldsetContext.Provider, {
@@ -553,14 +808,19 @@ function ShippingAddressFieldsetSkeleton({ count = SHIPPING_ADDRESS_SKELETON_ROW
 	});
 }
 ShippingAddressFieldset.Skeleton = ShippingAddressFieldsetSkeleton;
-function BoundAddressTextField({ fieldKey, slug, className, label, placeholder, children, fieldsetCtx, fieldDescriptor }) {
+function BoundAddressTextField({ fieldKey, slug, className, label, invalidMessage = "", placeholder, children, fieldsetCtx }) {
 	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, fieldKey);
-	const resolvedLabel = resolveAuthoredCopy(label, fieldDescriptor.label);
-	const rule = fieldsetCtx.ruleFor(fieldKey, resolvedLabel);
+	const { ruleFor } = fieldsetCtx;
+	const rule = useMemo(() => ruleFor(fieldKey, label, invalidMessage), [
+		ruleFor,
+		fieldKey,
+		label,
+		invalidMessage
+	]);
 	useRewordErroredField(name, rule);
 	return /* @__PURE__ */ jsx(FieldBinding, {
 		name,
-		label: resolvedLabel,
+		label,
 		placeholder,
 		defaultValue: fieldsetCtx.seedFor(fieldKey),
 		rule,
@@ -581,130 +841,124 @@ function BoundAddressTextField({ fieldKey, slug, className, label, placeholder,
 * too, against the active country's format.
 * Pre-filled from clientProfile, editable, required.
 */
-function ShippingAddressRecipientNameControl({ className, label, placeholder, children }) {
+function ShippingAddressRecipientNameControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("recipientName");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressRecipientNameContent, $content);
+	if (!fieldsetCtx.fieldFor("recipientName")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "recipientName",
 		slug: "recipient-name",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
 /** StreetControl */
-function ShippingAddressStreetControl({ className, label, placeholder, children }) {
+function ShippingAddressStreetControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("street");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressStreetContent, $content);
+	if (!fieldsetCtx.fieldFor("street")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "street",
 		slug: "street",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
 /** NumberControl */
-function ShippingAddressNumberControl({ className, label, placeholder, children }) {
+function ShippingAddressNumberControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("number");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressNumberContent, $content);
+	if (!fieldsetCtx.fieldFor("number")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "number",
 		slug: "number",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
 /** CityControl */
-function ShippingAddressCityControl({ className, label, placeholder, children }) {
+function ShippingAddressCityControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("city");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressCityContent, $content);
+	if (!fieldsetCtx.fieldFor("city")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "city",
 		slug: "city",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
-/** StateControl */
-function ShippingAddressStateControl({ className, label, placeholder, children }) {
+/** StateControl — its label is worded per country (`state`, `province`). */
+function ShippingAddressStateControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("state");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressStateContent, $content);
+	if (!fieldsetCtx.fieldFor("state")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "state",
 		slug: "state",
 		className,
-		label,
+		label: format("label", { country: fieldsetCtx.country }),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
-/** PostalCodeControl */
-function ShippingAddressPostalCodeControl({ className, label, placeholder, children }) {
+/** PostalCodeControl — its label and format message are worded per country. */
+function ShippingAddressPostalCodeControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("postalCode");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressPostalCodeContent, $content);
+	if (!fieldsetCtx.fieldFor("postalCode")) return null;
+	const country = fieldsetCtx.country;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "postalCode",
 		slug: "postal-code",
 		className,
-		label,
+		label: format("label", { country }),
+		invalidMessage: format("invalidMessage", { country }),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
 /** ComplementControl */
-function ShippingAddressComplementControl({ className, label, placeholder, children }) {
+function ShippingAddressComplementControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("complement");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressComplementContent, $content);
+	if (!fieldsetCtx.fieldFor("complement")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "complement",
 		slug: "complement",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
 /** NeighborhoodControl (BR-specific in v1) */
-function ShippingAddressNeighborhoodControl({ className, label, placeholder, children }) {
+function ShippingAddressNeighborhoodControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
-	const fieldDescriptor = fieldsetCtx.fieldFor("neighborhood");
-	if (!fieldDescriptor) return null;
+	const { format } = useMessageFormatter(ShippingAddressNeighborhoodContent, $content);
+	if (!fieldsetCtx.fieldFor("neighborhood")) return null;
 	return /* @__PURE__ */ jsx(BoundAddressTextField, {
 		fieldKey: "neighborhood",
 		slug: "neighborhood",
 		className,
-		label,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
-		fieldDescriptor,
 		children
 	});
 }
@@ -714,24 +968,25 @@ function ShippingAddressNeighborhoodControl({ className, label, placeholder, chi
 * none): a country with no descriptor renders no controls at all (Decision 3/4's "no entry, no
 * control" applied to the field that selects the entry itself).
 */
-function ShippingAddressCountryControl({ className, label, placeholder, children }) {
+function ShippingAddressCountryControl({ className, placeholder, children, $content }) {
 	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const { format } = useMessageFormatter(ShippingAddressCountryContent, $content);
 	if (!fieldsetCtx.descriptor) return null;
 	return /* @__PURE__ */ jsx(BoundShippingAddressCountryControl, {
 		className,
-		label,
-		defaultLabel: fieldsetCtx.descriptor.countryLabel,
+		label: format("label"),
 		placeholder,
 		fieldsetCtx,
 		children
 	});
 }
-function BoundShippingAddressCountryControl({ className, label, defaultLabel, placeholder, children, fieldsetCtx }) {
+function BoundShippingAddressCountryControl({ className, label, placeholder, children, fieldsetCtx }) {
 	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, "country");
+	const { displayName } = useStorefrontFormatters();
 	return /* @__PURE__ */ jsx(FieldBinding, {
 		name,
-		label: resolveAuthoredCopy(label, defaultLabel),
-		placeholder: placeholder ?? fieldsetCtx.descriptor?.label,
+		label,
+		placeholder: placeholder ?? countryDisplayName(fieldsetCtx.descriptor?.iso, displayName) ?? void 0,
 		defaultValue: fieldsetCtx.seedFor("country"),
 		options: fieldsetCtx.countryOptions,
 		autoComplete: FIELD_AUTOCOMPLETE.country,
@@ -770,6 +1025,6 @@ const ShippingAddress = {
 	CountryControlDefinition: ShippingAddressCountryControlDefinition
 };
 //#endregion
-export { ShippingAddress, ShippingAddressCityControl, ShippingAddressCityControlDefinition, ShippingAddressComplementControl, ShippingAddressComplementControlDefinition, ShippingAddressCountryControl, ShippingAddressCountryControlDefinition, ShippingAddressFieldset, ShippingAddressFieldsetDefinition, ShippingAddressFieldsetSkeleton, ShippingAddressNeighborhoodControl, ShippingAddressNeighborhoodControlDefinition, ShippingAddressNumberControl, ShippingAddressNumberControlDefinition, ShippingAddressPostalCodeControl, ShippingAddressPostalCodeControlDefinition, ShippingAddressRecipientNameControl, ShippingAddressRecipientNameControlDefinition, ShippingAddressStateControl, ShippingAddressStateControlDefinition, ShippingAddressStreetControl, ShippingAddressStreetControlDefinition };
+export { SHIPPING_ADDRESS_FIELDSET_ERROR_FIELDS, ShippingAddress, ShippingAddressCityContent, ShippingAddressCityControl, ShippingAddressCityControlDefinition, ShippingAddressComplementContent, ShippingAddressComplementControl, ShippingAddressComplementControlDefinition, ShippingAddressCountryContent, ShippingAddressCountryControl, ShippingAddressCountryControlDefinition, ShippingAddressFieldset, ShippingAddressFieldsetContent, ShippingAddressFieldsetDefinition, ShippingAddressFieldsetSkeleton, ShippingAddressNeighborhoodContent, ShippingAddressNeighborhoodControl, ShippingAddressNeighborhoodControlDefinition, ShippingAddressNumberContent, ShippingAddressNumberControl, ShippingAddressNumberControlDefinition, ShippingAddressPostalCodeContent, ShippingAddressPostalCodeControl, ShippingAddressPostalCodeControlDefinition, ShippingAddressRecipientNameContent, ShippingAddressRecipientNameControl, ShippingAddressRecipientNameControlDefinition, ShippingAddressStateContent, ShippingAddressStateControl, ShippingAddressStateControlDefinition, ShippingAddressStreetContent, ShippingAddressStreetControl, ShippingAddressStreetControlDefinition };
 
 //# sourceMappingURL=shipping-address.js.map