@vtex/faststore 0.0.10 → 0.0.12

package/dist/matter/shipping-address/library-country-descriptors.js

@@ -0,0 +1,136 @@
+import { addressFields } from "../../sdk/address/address-fields.js";
+import { loadCountryRules } from "../../sdk/address/country-rules.js";
+import { validateAddress } from "../../sdk/address/validate-address.js";
+import { normalizePostalCode } from "../../sdk/address/postal-code.js";
+import { useEffect, useSyncExternalStore } from "react";
+//#region src/matter/shipping-address/library-country-descriptors.ts
+/**
+* Country descriptors built from `@vtex/country-forms` at runtime, for the countries the hand-written
+* `countryDescriptors` table does not hold.
+*
+* A library-backed descriptor takes its field names and order, its `required` flags and its postal-code
+* verdict from the library, through `sdk/address/`. Nothing about those countries is written down here but
+* the list of ISO codes: like every descriptor it holds no copy. The library loads one chunk per
+* country, asynchronously, so a built descriptor lives in a module-level cache that `getCountryDescriptor`
+* and `getAvailableCountries` read synchronously: a country is absent until its chunk arrives, and a
+* descriptor is never returned half built.
+*
+* `BillingAddress` and `ShippingAddress` call `useLibraryCountryDescriptors` once. It starts the load when
+* the component mounts and re-renders it when a country arrives. A server render never reads the cache.
+*/
+/**
+* The countries whose descriptor comes from `@vtex/country-forms`, in the order the selectors list them.
+* Both are flat field lists, and both are countries `PAYMENT_COUNTRIES` already serves with a cardholder
+* document. A country with a dependent select needs a control the descriptor model cannot express.
+*/
+const LIBRARY_COUNTRIES = ["CAN", "MEX"];
+/**
+* The postal-code verdict of a library-backed country: `true` for a blank value (blankness belongs to the
+* required rule), else whether the library accepts the postal code. Only the `postalCode` key of the
+* library's answer is read, so a free-text `state`, which the SDK would check against the library's list,
+* never counts here.
+*/
+function postalCodeValidator(rules) {
+	return (value) => {
+		if (value.trim() === "") return true;
+		return validateAddress({ postalCode: value }, rules).postalCode === void 0;
+	};
+}
+/**
+* Builds the descriptor of a library-backed country from its loaded rules. `recipientName` comes first and is
+* required, like every other descriptor's; the rest is the library's field set, in its order, with its
+* `required` flags. `state` stays a free-text field.
+*/
+function buildLibraryDescriptor(iso, rules) {
+	return {
+		iso,
+		fields: [{
+			name: "recipientName",
+			required: true
+		}, ...addressFields(rules, {}).map(({ name, required }) => ({
+			name,
+			...required ? { required: true } : {},
+			...name === "postalCode" ? {
+				rule: { validate: postalCodeValidator(rules) },
+				normalize: (value) => normalizePostalCode(value, rules)
+			} : {}
+		}))]
+	};
+}
+const SERVER_STATE = {
+	loaded: [],
+	settled: false
+};
+const cache$1 = /* @__PURE__ */ new Map();
+const inFlight = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Set();
+let started = false;
+let state = SERVER_STATE;
+/** Recomputes the snapshot and tells the subscribers, only when something they can read changed. */
+function publish() {
+	const loaded = LIBRARY_COUNTRIES.filter((iso) => cache$1.has(iso));
+	const settled = started && inFlight.size === 0;
+	if (state.settled === settled && state.loaded.length === loaded.length && state.loaded.every((iso, index) => iso === loaded[index])) return;
+	state = {
+		loaded,
+		settled
+	};
+	for (const listener of listeners) listener();
+}
+async function loadOne(iso) {
+	try {
+		cache$1.set(iso, buildLibraryDescriptor(iso, await loadCountryRules(iso)));
+	} catch {} finally {
+		inFlight.delete(iso);
+		publish();
+	}
+}
+/**
+* Starts the load of every library-backed country that is neither loaded nor loading, and resolves once
+* every one of them has settled. Idempotent, and it never rejects: a country whose chunk fails is left out
+* of the cache and the next call tries it again.
+*/
+function loadLibraryCountryDescriptors() {
+	started = true;
+	const pending = LIBRARY_COUNTRIES.filter((iso) => !cache$1.has(iso)).map((iso) => {
+		const running = inFlight.get(iso);
+		if (running) return running;
+		const next = loadOne(iso);
+		inFlight.set(iso, next);
+		return next;
+	});
+	publish();
+	return Promise.all(pending).then(() => void 0);
+}
+/** The descriptor of a library-backed country once it has loaded, else `undefined`. */
+function getLoadedLibraryCountry(iso) {
+	return cache$1.get(iso);
+}
+function subscribe(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+function getSnapshot() {
+	return state;
+}
+function getServerSnapshot() {
+	return SERVER_STATE;
+}
+/**
+* Starts the load when the component mounts and re-renders it as countries arrive. `loaded` lists the
+* library-backed countries whose descriptor is available; `settled` is true once no load is running, whether
+* a country arrived or failed. On the server, and on the first client render of a hydrating tree, it reads
+* nothing loaded.
+*/
+function useLibraryCountryDescriptors() {
+	useEffect(() => {
+		loadLibraryCountryDescriptors();
+	}, []);
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//#endregion
+export { LIBRARY_COUNTRIES, buildLibraryDescriptor, getLoadedLibraryCountry, loadLibraryCountryDescriptors, useLibraryCountryDescriptors };
+
+//# sourceMappingURL=library-country-descriptors.js.map

package/dist/matter/shipping-address/library-country-descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-country-descriptors.js","names":["cache"],"sources":["../../../src/matter/shipping-address/library-country-descriptors.ts"],"sourcesContent":["/**\n * Country descriptors built from `@vtex/country-forms` at runtime, for the countries the hand-written\n * `countryDescriptors` table does not hold.\n *\n * A library-backed descriptor takes its field names and order, its `required` flags and its postal-code\n * verdict from the library, through `sdk/address/`. Nothing about those countries is written down here but\n * the list of ISO codes: like every descriptor it holds no copy. The library loads one chunk per\n * country, asynchronously, so a built descriptor lives in a module-level cache that `getCountryDescriptor`\n * and `getAvailableCountries` read synchronously: a country is absent until its chunk arrives, and a\n * descriptor is never returned half built.\n *\n * `BillingAddress` and `ShippingAddress` call `useLibraryCountryDescriptors` once. It starts the load when\n * the component mounts and re-renders it when a country arrives. A server render never reads the cache.\n */\n\nimport { useEffect, useSyncExternalStore } from 'react';\nimport { addressFields } from '../../sdk/address/address-fields.js';\nimport { loadCountryRules } from '../../sdk/address/country-rules.js';\nimport { normalizePostalCode } from '../../sdk/address/postal-code.js';\nimport type { CountryRules } from '../../sdk/address/types.js';\nimport { validateAddress } from '../../sdk/address/validate-address.js';\nimport type { CountryDescriptor, FieldDescriptor } from './country-descriptors.js';\n\n/**\n * The countries whose descriptor comes from `@vtex/country-forms`, in the order the selectors list them.\n * Both are flat field lists, and both are countries `PAYMENT_COUNTRIES` already serves with a cardholder\n * document. A country with a dependent select needs a control the descriptor model cannot express.\n */\nexport const LIBRARY_COUNTRIES: readonly string[] = ['CAN', 'MEX'];\n\n/**\n * The postal-code verdict of a library-backed country: `true` for a blank value (blankness belongs to the\n * required rule), else whether the library accepts the postal code. Only the `postalCode` key of the\n * library's answer is read, so a free-text `state`, which the SDK would check against the library's list,\n * never counts here.\n */\nfunction postalCodeValidator(rules: CountryRules): (value: string) => boolean {\n  return (value) => {\n    if (value.trim() === '') return true;\n    return validateAddress({ postalCode: value }, rules).postalCode === undefined;\n  };\n}\n\n/**\n * Builds the descriptor of a library-backed country from its loaded rules. `recipientName` comes first and is\n * required, like every other descriptor's; the rest is the library's field set, in its order, with its\n * `required` flags. `state` stays a free-text field.\n */\nexport function buildLibraryDescriptor(iso: string, rules: CountryRules): CountryDescriptor {\n  const fields: FieldDescriptor[] = [\n    { name: 'recipientName', required: true },\n    ...addressFields(rules, {}).map(\n      ({ name, required }): FieldDescriptor => ({\n        name,\n        ...(required ? { required: true } : {}),\n        ...(name === 'postalCode'\n          ? {\n              rule: { validate: postalCodeValidator(rules) },\n              normalize: (value: string) => normalizePostalCode(value, rules),\n            }\n          : {}),\n      }),\n    ),\n  ];\n\n  return { iso, fields };\n}\n\ntype LibraryDescriptorsState = Readonly<{ loaded: readonly string[]; settled: boolean }>;\n\nconst SERVER_STATE: LibraryDescriptorsState = { loaded: [], settled: false };\n\nconst cache = new Map<string, CountryDescriptor>();\nconst inFlight = new Map<string, Promise<void>>();\nconst listeners = new Set<() => void>();\nlet started = false;\nlet state: LibraryDescriptorsState = SERVER_STATE;\n\n/** Recomputes the snapshot and tells the subscribers, only when something they can read changed. */\nfunction publish(): void {\n  const loaded = LIBRARY_COUNTRIES.filter((iso) => cache.has(iso));\n  const settled = started && inFlight.size === 0;\n  const unchanged =\n    state.settled === settled &&\n    state.loaded.length === loaded.length &&\n    state.loaded.every((iso, index) => iso === loaded[index]);\n  if (unchanged) return;\n\n  state = { loaded, settled };\n  for (const listener of listeners) listener();\n}\n\nasync function loadOne(iso: string): Promise<void> {\n  try {\n    cache.set(iso, buildLibraryDescriptor(iso, await loadCountryRules(iso)));\n  } catch {\n    // A failed country stays out of the cache, so both forms treat it as a country with no descriptor.\n    // Nothing is reported: the error could carry the request, and the next load retries it.\n  } finally {\n    inFlight.delete(iso);\n    publish();\n  }\n}\n\n/**\n * Starts the load of every library-backed country that is neither loaded nor loading, and resolves once\n * every one of them has settled. Idempotent, and it never rejects: a country whose chunk fails is left out\n * of the cache and the next call tries it again.\n */\nexport function loadLibraryCountryDescriptors(): Promise<void> {\n  started = true;\n  const pending = LIBRARY_COUNTRIES.filter((iso) => !cache.has(iso)).map((iso) => {\n    const running = inFlight.get(iso);\n    if (running) return running;\n    const next = loadOne(iso);\n    inFlight.set(iso, next);\n    return next;\n  });\n  publish();\n  return Promise.all(pending).then(() => undefined);\n}\n\n/** The descriptor of a library-backed country once it has loaded, else `undefined`. */\nexport function getLoadedLibraryCountry(iso: string): CountryDescriptor | undefined {\n  return cache.get(iso);\n}\n\nfunction subscribe(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\nfunction getSnapshot(): LibraryDescriptorsState {\n  return state;\n}\n\nfunction getServerSnapshot(): LibraryDescriptorsState {\n  return SERVER_STATE;\n}\n\n/**\n * Starts the load when the component mounts and re-renders it as countries arrive. `loaded` lists the\n * library-backed countries whose descriptor is available; `settled` is true once no load is running, whether\n * a country arrived or failed. On the server, and on the first client render of a hydrating tree, it reads\n * nothing loaded.\n */\nexport function useLibraryCountryDescriptors(): LibraryDescriptorsState {\n  useEffect(() => {\n    void loadLibraryCountryDescriptors();\n  }, []);\n  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,oBAAuC,CAAC,OAAO,KAAK;;;;;;;AAQjE,SAAS,oBAAoB,OAAiD;CAC5E,QAAQ,UAAU;EAChB,IAAI,MAAM,KAAK,MAAM,IAAI,OAAO;EAChC,OAAO,gBAAgB,EAAE,YAAY,MAAM,GAAG,KAAK,CAAC,CAAC,eAAe,KAAA;CACtE;AACF;;;;;;AAOA,SAAgB,uBAAuB,KAAa,OAAwC;CAiB1F,OAAO;EAAE;EAAK,QAAA,CAfZ;GAAE,MAAM;GAAiB,UAAU;EAAK,GACxC,GAAG,cAAc,OAAO,CAAC,CAAC,CAAC,CAAC,KACzB,EAAE,MAAM,gBAAiC;GACxC;GACA,GAAI,WAAW,EAAE,UAAU,KAAK,IAAI,CAAC;GACrC,GAAI,SAAS,eACT;IACE,MAAM,EAAE,UAAU,oBAAoB,KAAK,EAAE;IAC7C,YAAY,UAAkB,oBAAoB,OAAO,KAAK;GAChE,IACA,CAAC;EACP,EACF,CAGiB;CAAE;AACvB;AAIA,MAAM,eAAwC;CAAE,QAAQ,CAAC;CAAG,SAAS;AAAM;AAE3E,MAAMA,0BAAQ,IAAI,IAA+B;AACjD,MAAM,2BAAW,IAAI,IAA2B;AAChD,MAAM,4BAAY,IAAI,IAAgB;AACtC,IAAI,UAAU;AACd,IAAI,QAAiC;;AAGrC,SAAS,UAAgB;CACvB,MAAM,SAAS,kBAAkB,QAAQ,QAAQA,QAAM,IAAI,GAAG,CAAC;CAC/D,MAAM,UAAU,WAAW,SAAS,SAAS;CAK7C,IAHE,MAAM,YAAY,WAClB,MAAM,OAAO,WAAW,OAAO,UAC/B,MAAM,OAAO,OAAO,KAAK,UAAU,QAAQ,OAAO,MAAM,GAC3C;CAEf,QAAQ;EAAE;EAAQ;CAAQ;CAC1B,KAAK,MAAM,YAAY,WAAW,SAAS;AAC7C;AAEA,eAAe,QAAQ,KAA4B;CACjD,IAAI;EACF,QAAM,IAAI,KAAK,uBAAuB,KAAK,MAAM,iBAAiB,GAAG,CAAC,CAAC;CACzE,QAAQ,CAGR,UAAU;EACR,SAAS,OAAO,GAAG;EACnB,QAAQ;CACV;AACF;;;;;;AAOA,SAAgB,gCAA+C;CAC7D,UAAU;CACV,MAAM,UAAU,kBAAkB,QAAQ,QAAQ,CAACA,QAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;EAC9E,MAAM,UAAU,SAAS,IAAI,GAAG;EAChC,IAAI,SAAS,OAAO;EACpB,MAAM,OAAO,QAAQ,GAAG;EACxB,SAAS,IAAI,KAAK,IAAI;EACtB,OAAO;CACT,CAAC;CACD,QAAQ;CACR,OAAO,QAAQ,IAAI,OAAO,CAAC,CAAC,WAAW,KAAA,CAAS;AAClD;;AAGA,SAAgB,wBAAwB,KAA4C;CAClF,OAAOA,QAAM,IAAI,GAAG;AACtB;AAEA,SAAS,UAAU,UAAkC;CACnD,UAAU,IAAI,QAAQ;CACtB,aAAa;EACX,UAAU,OAAO,QAAQ;CAC3B;AACF;AAEA,SAAS,cAAuC;CAC9C,OAAO;AACT;AAEA,SAAS,oBAA6C;CACpD,OAAO;AACT;;;;;;;AAQA,SAAgB,+BAAwD;CACtE,gBAAgB;EACd,8BAAmC;CACrC,GAAG,CAAC,CAAC;CACL,OAAO,qBAAqB,WAAW,aAAa,iBAAiB;AACvE"}

package/dist/matter/shipping-address/shipping-address.d.ts

@@ -1,3 +1,4 @@
+import { ContentValue, MessageLocaleProp } from "../../core/dist/define-content-type.js";
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ComponentActions } from "../../sdk/actions/types.js";
@@ -31,94 +32,360 @@ export type ShippingAddressFieldsetData = {
     lastName?: string | null;
   } | null;
 } | null;
-export type ShippingAddressFieldsetProps = {
+export type ShippingAddressFieldsetProps = MessageLocaleProp & {
   /** Country used when the stored address has none. */
   defaultCountry?: string;
   /** Placeholder rows the loading skeleton draws. Set it to the number of Controls composed here. */
   skeletonCount?: number;
-  /** Announced politely while the address resolves. Blank means no announcement. */
-  loadingLabel?: string;
-  /** Announced politely once the Controls mount. Blank means no announcement. */
-  loadedLabel?: string;
-  /** Accessible name of the `<fieldset>` group. Blank means no name is exposed. */
-  groupLabel?: string;
   className?: string;
   children?: ReactNode;
   /** `ShippingAddressFieldsetData` forwarded by the reactive runtime. */
   $data?: ShippingAddressFieldsetData;
   /** Compiler-injected action surface; carries `shipping.setAddress`. */
   $actions?: ComponentActions;
+  /** The two announcements, the group's accessible name and the required-field message. */
+  $content?: ContentValue<typeof ShippingAddressFieldsetContent>;
 };
-export type ShippingAddressStreetControlProps = {
+export type ShippingAddressStreetControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressStreetContent>;
 };
-export type ShippingAddressNumberControlProps = {
+export type ShippingAddressNumberControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressNumberContent>;
 };
-export type ShippingAddressCityControlProps = {
+export type ShippingAddressCityControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressCityContent>;
 };
-export type ShippingAddressStateControlProps = {
+export type ShippingAddressStateControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressStateContent>;
 };
-export type ShippingAddressPostalCodeControlProps = {
+export type ShippingAddressPostalCodeControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressPostalCodeContent>;
 };
-export type ShippingAddressComplementControlProps = {
+export type ShippingAddressComplementControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressComplementContent>;
 };
-export type ShippingAddressNeighborhoodControlProps = {
+export type ShippingAddressNeighborhoodControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressNeighborhoodContent>;
 };
-export type ShippingAddressCountryControlProps = {
+export type ShippingAddressCountryControlProps = MessageLocaleProp & {
   className?: string;
-  label?: string;
+  /** Shown when the field has no value. Absence shows the active country's name. */
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, FieldSelect.Root, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressCountryContent>;
 };
-export type ShippingAddressRecipientNameControlProps = {
+export type ShippingAddressRecipientNameControlProps = MessageLocaleProp & {
   className?: string;
-  /** Overrides the descriptor's label. Absence means the platform's value. */
-  label?: string;
   placeholder?: string;
   /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
+  $content?: ContentValue<typeof ShippingAddressRecipientNameContent>;
+};
+export declare const ShippingAddressFieldsetContent: {
+  readonly id: "shipping-address-fieldset";
+  readonly title: "Shipping Address Fieldset";
+  readonly description: "Announcements and accessible name of the delivery address group, and its required-field message.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly loadingLabel: {
+        readonly type: "string";
+        readonly title: "Loading announcement";
+        readonly description: "Announced politely while the address resolves.";
+        readonly format: "icu-message";
+        readonly messageSource: "Loading your delivery address";
+      };
+      readonly loadedLabel: {
+        readonly type: "string";
+        readonly title: "Loaded announcement";
+        readonly description: "Announced politely once the fields mount.";
+        readonly format: "icu-message";
+        readonly messageSource: "Your delivery address is ready";
+      };
+      readonly groupLabel: {
+        readonly type: "string";
+        readonly title: "Accessible group name";
+        readonly description: "A composed FieldsetLegend wins over it.";
+        readonly format: "icu-message";
+        readonly messageSource: "Your delivery address";
+        readonly messageOptional: true;
+      };
+      readonly requiredMessage: {
+        readonly type: "string";
+        readonly title: "Required field message";
+        readonly description: "Shown under a required field left blank; label is that field's label.";
+        readonly format: "icu-message";
+        readonly messageSource: "{label} is required";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly label: {
+              readonly type: "string";
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly label: "recipient name";
+        };
+      };
+      readonly missingRecipientNameMessage: {
+        readonly type: "string";
+        readonly title: "Missing recipient name message";
+        readonly description: "Shown by FormError when the server refuses a blank recipient name.";
+        readonly format: "icu-message";
+        readonly messageSource: "Enter the recipient's name.";
+      };
+      readonly invalidPostalCodeMessage: {
+        readonly type: "string";
+        readonly title: "Invalid postal code message";
+        readonly description: "Shown by FormError when the server refuses the postal code.";
+        readonly format: "icu-message";
+        readonly messageSource: "Enter a valid postal code.";
+      };
+      readonly invalidAddressMessage: {
+        readonly type: "string";
+        readonly title: "Invalid address message";
+        readonly description: "Shown by FormError when the server refuses the address.";
+        readonly format: "icu-message";
+        readonly messageSource: "Check the address and try again.";
+      };
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Generic error message";
+        readonly description: "Shown by FormError for a network failure or a refusal the shopper cannot fix.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your delivery address. Please try again.";
+      };
+    };
+  };
+};
+export declare const ShippingAddressRecipientNameContent: {
+  readonly id: "shipping-address-recipient-name";
+  readonly title: "Shipping Address Recipient Name";
+  readonly description: "Label of the recipient name field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "recipient name";
+      };
+    };
+  };
+};
+export declare const ShippingAddressStreetContent: {
+  readonly id: "shipping-address-street";
+  readonly title: "Shipping Address Street";
+  readonly description: "Label of the street field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "street";
+      };
+    };
+  };
+};
+export declare const ShippingAddressNumberContent: {
+  readonly id: "shipping-address-number";
+  readonly title: "Shipping Address Number";
+  readonly description: "Label of the number field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "number";
+      };
+    };
+  };
+};
+export declare const ShippingAddressComplementContent: {
+  readonly id: "shipping-address-complement";
+  readonly title: "Shipping Address Complement";
+  readonly description: "Label of the complement field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "apartment, suite, etc. (optional)";
+      };
+    };
+  };
+};
+export declare const ShippingAddressNeighborhoodContent: {
+  readonly id: "shipping-address-neighborhood";
+  readonly title: "Shipping Address Neighborhood";
+  readonly description: "Label of the neighborhood field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "neighborhood";
+      };
+    };
+  };
+};
+export declare const ShippingAddressCityContent: {
+  readonly id: "shipping-address-city";
+  readonly title: "Shipping Address City";
+  readonly description: "Label of the city field of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "city";
+      };
+    };
+  };
+};
+export declare const ShippingAddressStateContent: {
+  readonly id: "shipping-address-state";
+  readonly title: "Shipping Address State";
+  readonly description: "Label of the state field of the delivery address, worded per country.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly description: "country is the active country (ISO 3166-1 alpha-3).";
+        readonly format: "icu-message";
+        readonly messageSource: "{country, select, CAN {province} other {state}}";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly country: {
+              readonly type: "string";
+              readonly enum: readonly ["BRA", "USA", "CAN", "MEX"];
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly country: "CAN";
+        };
+      };
+    };
+  };
+};
+export declare const ShippingAddressPostalCodeContent: {
+  readonly id: "shipping-address-postal-code";
+  readonly title: "Shipping Address Postal Code";
+  readonly description: "Label of the postal code field of the delivery address and its format message, worded per country.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly description: "country is the active country (ISO 3166-1 alpha-3).";
+        readonly format: "icu-message";
+        readonly messageSource: "{country, select, USA {zip code} other {postal code}}";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly country: {
+              readonly type: "string";
+              readonly enum: readonly ["BRA", "USA", "CAN", "MEX"];
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly country: "USA";
+        };
+      };
+      readonly invalidMessage: {
+        readonly type: "string";
+        readonly title: "Invalid postal code message";
+        readonly description: "Shown under a postal code not in the active country's format. Never contains the typed value.";
+        readonly format: "icu-message";
+        readonly messageSource: "{country, select, USA {invalid zip code} other {invalid postal code}}";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly country: {
+              readonly type: "string";
+              readonly enum: readonly ["BRA", "USA", "CAN", "MEX"];
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly country: "USA";
+        };
+      };
+    };
+  };
+};
+export declare const ShippingAddressCountryContent: {
+  readonly id: "shipping-address-country";
+  readonly title: "Shipping Address Country";
+  readonly description: "Label of the country selector of the delivery address.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Field label";
+        readonly format: "icu-message";
+        readonly messageSource: "country";
+      };
+    };
+  };
 };
 export declare const ShippingAddressFieldsetDefinition: ComponentDefinition<ShippingAddressFieldsetProps>;
 export declare const ShippingAddressRecipientNameControlDefinition: ComponentDefinition<ShippingAddressRecipientNameControlProps>;
@@ -157,7 +424,7 @@ export declare const ShippingAddressCountryControlDefinition: ComponentDefinitio
  * 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.
  */
-export declare function ShippingAddressFieldset({ defaultCountry, skeletonCount, loadingLabel, loadedLabel, groupLabel, className, children, $data: $dataProp, $actions: $actionsProp }: ShippingAddressFieldsetProps): ReactNode;
+export declare function ShippingAddressFieldset({ defaultCountry, skeletonCount, className, children, $data: $dataProp, $actions: $actionsProp, $content }: ShippingAddressFieldsetProps): ReactNode;
 export declare namespace ShippingAddressFieldset {
   var Skeleton: typeof ShippingAddressFieldsetSkeleton;
 }
@@ -174,28 +441,28 @@ export declare function ShippingAddressFieldsetSkeleton({ count, className, ...p
  * too, against the active country's format.
  * Pre-filled from clientProfile, editable, required.
  */
-export declare function ShippingAddressRecipientNameControl({ className, label, placeholder, children }: ShippingAddressRecipientNameControlProps): ReactNode;
+export declare function ShippingAddressRecipientNameControl({ className, placeholder, children, $content }: ShippingAddressRecipientNameControlProps): ReactNode;
 /** StreetControl */
-export declare function ShippingAddressStreetControl({ className, label, placeholder, children }: ShippingAddressStreetControlProps): ReactNode;
+export declare function ShippingAddressStreetControl({ className, placeholder, children, $content }: ShippingAddressStreetControlProps): ReactNode;
 /** NumberControl */
-export declare function ShippingAddressNumberControl({ className, label, placeholder, children }: ShippingAddressNumberControlProps): ReactNode;
+export declare function ShippingAddressNumberControl({ className, placeholder, children, $content }: ShippingAddressNumberControlProps): ReactNode;
 /** CityControl */
-export declare function ShippingAddressCityControl({ className, label, placeholder, children }: ShippingAddressCityControlProps): ReactNode;
-/** StateControl */
-export declare function ShippingAddressStateControl({ className, label, placeholder, children }: ShippingAddressStateControlProps): ReactNode;
-/** PostalCodeControl */
-export declare function ShippingAddressPostalCodeControl({ className, label, placeholder, children }: ShippingAddressPostalCodeControlProps): ReactNode;
+export declare function ShippingAddressCityControl({ className, placeholder, children, $content }: ShippingAddressCityControlProps): ReactNode;
+/** StateControl — its label is worded per country (`state`, `province`). */
+export declare function ShippingAddressStateControl({ className, placeholder, children, $content }: ShippingAddressStateControlProps): ReactNode;
+/** PostalCodeControl — its label and format message are worded per country. */
+export declare function ShippingAddressPostalCodeControl({ className, placeholder, children, $content }: ShippingAddressPostalCodeControlProps): ReactNode;
 /** ComplementControl */
-export declare function ShippingAddressComplementControl({ className, label, placeholder, children }: ShippingAddressComplementControlProps): ReactNode;
+export declare function ShippingAddressComplementControl({ className, placeholder, children, $content }: ShippingAddressComplementControlProps): ReactNode;
 /** NeighborhoodControl (BR-specific in v1) */
-export declare function ShippingAddressNeighborhoodControl({ className, label, placeholder, children }: ShippingAddressNeighborhoodControlProps): ReactNode;
+export declare function ShippingAddressNeighborhoodControl({ className, placeholder, children, $content }: ShippingAddressNeighborhoodControlProps): ReactNode;
 /**
  * CountryControl — moves onto `FieldSelect` (Decision 8): the trigger resolves a country name from
  * the field contract's `options`. Gated on `descriptor`, not on a per-field entry (country has
  * 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).
  */
-export declare function ShippingAddressCountryControl({ className, label, placeholder, children }: ShippingAddressCountryControlProps): ReactNode;
+export declare function ShippingAddressCountryControl({ className, placeholder, children, $content }: ShippingAddressCountryControlProps): ReactNode;
 export declare const ShippingAddress: {
   Fieldset: typeof ShippingAddressFieldset;
   FieldsetDefinition: ComponentDefinition<ShippingAddressFieldsetProps>;