@vtex/faststore 0.0.5 → 0.0.6

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

@@ -1,23 +1,37 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
-import { Field } from "../../particles/field/field.js";
+import { Field, FieldBinding, FieldsetFieldContext, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset } from "../../particles/field/field.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
-import { Select } from "../../particles/select/select.js";
-import { AddressSummary, AddressSummaryRoot } from "../../particles/address-summary/address-summary.js";
-import "../../sdk/shipping/shipping-operations.js";
+import { Fieldset } from "../../particles/fieldset/fieldset.js";
 import { getAvailableCountries, getCountryDescriptor } from "./country-descriptors.js";
-import { cloneElement, createContext, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+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 { FieldSelect } from "../../particles/select/field-select.js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useWatch } from "react-hook-form";
 //#region src/matter/shipping-address/shipping-address.tsx
 /**
 * Shipping address step (T2 — Enter and save the delivery address).
 * Single-file matter per ADR-0001; batches form state and writes once via shipping.setAddress.
 * Controls are thin context-bound components that read/write draft state (docs/storefront-core/reference-cart.md § Delivery).
 */
-const fragment = `
-  fragment ShippingAddressData on Query {
+/**
+* The fieldset's own fragment. Drops `savedAddresses` — the fieldset has no saved-address UI of
+* its own (Decision 1 of specs/shipping-address-fieldset.md).
+*
+* `clientProfile` selects `id` even though nothing renders it. The reactive runtime resolves each
+* root field to a cache reference through `cache.identify`, which needs `__typename` and `id`; with
+* no `id` in the composed page query the profile never normalises, `useReactiveEntity` keeps
+* returning the server's `fallbackData`, and a page composing this fieldset without
+* `ClientProfileFieldset` would show a logged-in shopper a blank recipient name instead of the one
+* US-4 fills in from their profile.
+*/
+const fieldsetFragment = `
+  fragment ShippingAddressFieldsetData on Query {
     shipping {
       __typename
       id
@@ -34,370 +48,346 @@ const fragment = `
         city
         state
       }
-      savedAddresses {
-        __typename
-        id
-        recipientName
-        postalCode
-        country
-        street
-        number
-        complement
-        neighborhood
-        city
-        state
-      }
     }
     clientProfile {
       __typename
+      id
       firstName
       lastName
     }
   }
 `;
-const SHIPPING_ADDRESS_CONTEXT_UNSET = Symbol("ShippingAddressContextUnset");
-const ShippingAddressContext = createContext(SHIPPING_ADDRESS_CONTEXT_UNSET);
-function useShippingAddressContext() {
-	const ctx = useContext(ShippingAddressContext);
-	if (ctx === SHIPPING_ADDRESS_CONTEXT_UNSET) throw new Error("ShippingAddress components must be used inside ShippingAddressRoot.");
+/** The react-hook-form namespace every field of this entity registers under. */
+const SHIPPING_ADDRESS_NAMESPACE = "shippingAddress";
+const ShippingAddressFieldsetContext = createContext(null);
+/**
+* Read before any field hook (Decision 4): a control calls this before looking up its own
+* descriptor entry, so a field the active descriptor does not declare never calls
+* `useFieldsetField`/`useController` and so never registers with react-hook-form at all. Throws
+* when rendered with no `ShippingAddressFieldset` above it (Decision 2), naming the required
+* composition.
+*/
+function useShippingAddressFieldsetContext() {
+	const ctx = useContext(ShippingAddressFieldsetContext);
+	if (!ctx) throw new Error("ShippingAddress*Control components must be used inside ShippingAddressFieldset.");
 	return ctx;
 }
-const SHIPPING_ADDRESS_DRAWER_CONTEXT_UNSET = Symbol("ShippingAddressDrawerContextUnset");
-const ShippingAddressDrawerContext = createContext(SHIPPING_ADDRESS_DRAWER_CONTEXT_UNSET);
-function useShippingAddressDrawerContext() {
-	const ctx = useContext(ShippingAddressDrawerContext);
-	if (ctx === SHIPPING_ADDRESS_DRAWER_CONTEXT_UNSET) throw new Error("ShippingAddressSavedAddressDrawerController and ShippingAddressSavedAddressSubmit must be used inside ShippingAddressRoot.");
-	return ctx;
+/**
+* Rows `ShippingAddressFieldsetSkeleton` draws when nobody says otherwise: one per Control in the
+* full anatomy, the nine of them. It is a default and not a derivation — the skeleton renders before
+* any address has resolved, so it cannot read the live descriptor, and the composed Controls are
+* opaque children. A page that composes fewer than nine sets `skeletonCount` to what it composed,
+* or the form jumps by the difference when the Controls take the skeleton's place.
+*/
+const SHIPPING_ADDRESS_SKELETON_ROWS = 9;
+/** `autoComplete` tokens per field (US-3, WCAG 2.1 SC 1.3.5). `number` has no standard token. */
+const FIELD_AUTOCOMPLETE = {
+	recipientName: "name",
+	postalCode: "postal-code",
+	country: "country",
+	street: "address-line1",
+	number: void 0,
+	complement: "address-line2",
+	neighborhood: "address-level3",
+	city: "address-level2",
+	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.
+*/
+function buildRule(field, label) {
+	if (!field.required) return field.rule;
+	return {
+		...field.rule,
+		required: `${label} é obrigatório`
+	};
 }
-const SHIPPING_ADDRESS_SECTION_CONTEXT_UNSET = Symbol("ShippingAddressSectionContextUnset");
-const ShippingAddressSectionContext = createContext(SHIPPING_ADDRESS_SECTION_CONTEXT_UNSET);
-function useShippingAddressSectionContext() {
-	const ctx = useContext(ShippingAddressSectionContext);
-	if (ctx === SHIPPING_ADDRESS_SECTION_CONTEXT_UNSET) throw new Error("ShippingAddressSummaryView, ShippingAddressEditForm, ShippingAddressEditButton and ShippingAddressCancelButton must be used inside ShippingAddressEditController.");
-	return ctx;
+/** Keeps only the AddressDraft keys `values` actually defines — a field no control composed is absent, not `undefined`. */
+function pickDefinedAddressFields(values) {
+	const result = {};
+	for (const key of Object.keys(values)) {
+		const value = values[key];
+		if (value !== void 0) result[key] = value;
+	}
+	return result;
 }
-const ShippingAddressRootDefinition = defineComponent({
-	name: "ShippingAddressRoot",
+const ShippingAddressFieldsetDefinition = defineComponent({
+	name: "ShippingAddressFieldset",
 	importPath: "@vtex/faststore/components",
-	component: ShippingAddressRoot,
-	fragment,
+	component: ShippingAddressFieldset,
+	fragment: fieldsetFragment,
 	fetchStrategy: "reactive",
-	providesContext: "shipping-address",
+	skeleton: ShippingAddressFieldsetSkeleton,
 	actions: { shipping: ["setAddress"] },
+	requiresContext: "form",
+	providesContext: "shipping-address",
 	editor: {
-		label: "Shipping Address Root",
-		category: "content"
+		label: "Shipping Address Fieldset",
+		category: "commerce"
 	},
-	schema: { defaultCountry: {
-		type: "string",
-		default: "BRA",
-		label: "Default country (ISO-3)"
-	} },
-	guideline: "Country-adaptive single-address delivery form; batches all fields and writes once via shipping.setAddress. See shipping-address.md."
+	schema: {
+		defaultCountry: {
+			type: "string",
+			default: "BRA",
+			label: "Default country (ISO-3)"
+		},
+		skeletonCount: {
+			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."
 });
+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 ShippingAddressRecipientNameControlDefinition = defineComponent({
 	name: "ShippingAddressRecipientNameControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressRecipientNameControl,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "Recipient Name Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "Recipient-name input field; required for submit. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		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,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "Street Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "Street name input field. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		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,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "Number Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "Street number input field. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		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,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "City Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "City name input field. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		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,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "State Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "State/province input field. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		}
+	},
+	guideline: `State/province input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressPostalCodeControlDefinition = defineComponent({
 	name: "ShippingAddressPostalCodeControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressPostalCodeControl,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "Postal Code Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "Postal code input field. Must be a descendant of ShippingAddressRoot."
+	schema: {
+		label: {
+			type: "string",
+			label: "Field label"
+		},
+		placeholder: {
+			type: "string",
+			label: "Placeholder"
+		}
+	},
+	guideline: `Postal code input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
 const ShippingAddressComplementControlDefinition = defineComponent({
 	name: "ShippingAddressComplementControl",
 	importPath: "@vtex/faststore/components",
 	component: ShippingAddressComplementControl,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
 		label: "Complement Control",
 		category: "action"
 	},
-	schema: {},
-	guideline: "Complement (apartment, suite, etc.) input field. Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressNeighborhoodControlDefinition = defineComponent({
-	name: "ShippingAddressNeighborhoodControl",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressNeighborhoodControl,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Neighborhood Control",
-		category: "action"
-	},
-	schema: {},
-	guideline: "Neighborhood (bairro) input field; shown only for countries that have this field (BR in v1). Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressCountryControlDefinition = defineComponent({
-	name: "ShippingAddressCountryControl",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressCountryControl,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Country Control",
-		category: "action"
-	},
-	schema: { label: {
-		type: "string",
-		default: "país",
-		label: "Field label"
-	} },
-	guideline: "Country selector; lists only countries with an implemented descriptor. Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressSavedListDefinition = defineComponent({
-	name: "ShippingAddressSavedList",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSavedList,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Saved Address List",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "List of saved addresses for logged-in shoppers; renders only if savedAddresses is non-empty. Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressSavedOptionDefinition = defineComponent({
-	name: "ShippingAddressSavedOption",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSavedOption,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Saved Address Option",
-		category: "commerce"
-	},
-	schema: { id: {
-		type: "string",
-		label: "Saved address ID"
-	} },
-	guideline: "A single saved address option; renders its address via the same AddressSummary particle (through its own AddressSummaryRoot) used by ShippingAddressSelectedSummary, so both share one formatting implementation. Must be a descendant of ShippingAddressSavedList."
-});
-const ShippingAddressSubmitDefinition = defineComponent({
-	name: "ShippingAddressSubmit",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSubmit,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Shipping Address Submit",
-		category: "action"
-	},
 	schema: {
 		label: {
 			type: "string",
-			default: "salvar endereço",
-			label: "Button label"
+			label: "Field label"
 		},
-		pendingLabel: {
+		placeholder: {
 			type: "string",
-			default: "salvando...",
-			label: "Pending label"
+			label: "Placeholder"
 		}
 	},
-	guideline: "Submit button; dispatches the batched address write. Disabled until recipient name is non-blank. Must be a descendant of ShippingAddressRoot."
+	guideline: `Complement (apartment, suite, etc.) input field. ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
-const ShippingAddressErrorDefinition = defineComponent({
-	name: "ShippingAddressError",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressError,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Shipping Address Error",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "Error banner; shows domain validation errors inline or a generic upstream-error state. Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressSavedAddressDrawerControllerDefinition = defineComponent({
-	name: "ShippingAddressSavedAddressDrawerController",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSavedAddressDrawerController,
-	requiresContext: "shipping-address",
-	editor: {
-		label: "Saved Address Drawer Controller",
-		category: "action"
-	},
-	schema: {},
-	guideline: "Wraps a single DrawerRoot child (the saved-address selection drawer) and makes it controlled by the shipping-address drawer state: open state and blocked-dismissal-while-submitting are handled here, so do not set raw open/onOpenChange on the wrapped DrawerRoot. Compose as the parent of DrawerRoot, with the drawer trigger and popup as DrawerRoot descendants, same pattern as CartOpenOnAdd wrapping the mini-cart DrawerRoot. Must be inside ShippingAddressRoot."
-});
-const ShippingAddressSavedAddressSubmitDefinition = defineComponent({
-	name: "ShippingAddressSavedAddressSubmit",
+const ShippingAddressNeighborhoodControlDefinition = defineComponent({
+	name: "ShippingAddressNeighborhoodControl",
 	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSavedAddressSubmit,
+	component: ShippingAddressNeighborhoodControl,
 	requiresContext: "shipping-address",
+	providesContext: "field",
 	editor: {
-		label: "Saved Address Submit",
+		label: "Neighborhood Control",
 		category: "action"
 	},
 	schema: {
 		label: {
 			type: "string",
-			default: "selecionar",
-			label: "Button label"
+			label: "Field label"
 		},
-		pendingLabel: {
+		placeholder: {
 			type: "string",
-			default: "selecionando...",
-			label: "Pending label"
+			label: "Placeholder"
 		}
 	},
-	guideline: "The drawer's \"selecionar\" submit button; independent submitting state from the main form's Submit (Decision 7); no-ops when the selected saved address is already the current one (Decision 8). Must be inside the saved-address drawer's DrawerPopup and inside ShippingAddressRoot."
+	guideline: `Neighborhood (bairro) input field; shown only for countries that have this field (BR in v1). ${ADDRESS_TEXT_CONTROL_GUIDELINE_SUFFIX}`
 });
-const ShippingAddressSelectedSummaryDefinition = defineComponent({
-	name: "ShippingAddressSelectedSummary",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSelectedSummary,
-	requiresContext: "shipping-address",
-	providesContext: "address-summary",
-	editor: {
-		label: "Selected Address Summary",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "Provides the current delivery address to the generic AddressSummary particle via AddressSummaryRoot context, and renders the default AddressSummary when composed with no children. Compose AddressSummaryRecipient / Street / Locality directly to choose the order or drop a line. Self-gates to null when there is no current address yet. Must be a descendant of ShippingAddressRoot."
-});
-const ShippingAddressEditControllerDefinition = defineComponent({
-	name: "ShippingAddressEditController",
+const ShippingAddressCountryControlDefinition = defineComponent({
+	name: "ShippingAddressCountryControl",
 	importPath: "@vtex/faststore/components",
-	component: ShippingAddressEditController,
+	component: ShippingAddressCountryControl,
 	requiresContext: "shipping-address",
-	providesContext: "shipping-address-section",
-	editor: {
-		label: "Shipping Address Edit Controller",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "Owns the view/edit toggle for the delivery address section: defaults to view when a current address exists, edit otherwise; switches back to view automatically whenever setAddress succeeds (main form submit or saved-address drawer submit), without ShippingAddressSubmit/ShippingAddressSavedAddressSubmit needing to know about this mode. Compose a ShippingAddressSummaryView holding SelectedSummary + EditButton and a ShippingAddressEditForm holding the form Controls/Submit/Error. Self-contained: it decides from its own data and the shopper's own presses, so no other section opens it and finishing it opens nothing. Must be inside ShippingAddressRoot."
-});
-const ShippingAddressSummaryViewDefinition = defineComponent({
-	name: "ShippingAddressSummaryView",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressSummaryView,
-	requiresContext: "shipping-address-section",
-	editor: {
-		label: "Shipping Address Summary View",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "Renders its children only while the delivery section shows the saved-address summary, and nothing while it shows the form. Compose SelectedSummary and a ShippingAddressEditButton inside. Takes no props: which state it gates is which component it is. Must be inside a ShippingAddressEditController."
-});
-const ShippingAddressEditFormDefinition = defineComponent({
-	name: "ShippingAddressEditForm",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressEditForm,
-	requiresContext: "shipping-address-section",
-	editor: {
-		label: "Shipping Address Edit Form",
-		category: "commerce"
-	},
-	schema: {},
-	guideline: "Renders its children only while the delivery section shows the address form, and nothing while it shows the summary. Compose the Controls, Submit and Error parts inside. Must be inside a ShippingAddressEditController."
-});
-const ShippingAddressEditButtonDefinition = defineComponent({
-	name: "ShippingAddressEditButton",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressEditButton,
-	requiresContext: "shipping-address-section",
-	editor: {
-		label: "Shipping Address Edit Button",
-		category: "action"
-	},
-	schema: { label: {
-		type: "string",
-		default: "editar",
-		label: "Button label"
-	} },
-	guideline: "CTA that switches the view/edit mode to edit. Typically placed inside a ShippingAddressSummaryView, next to SelectedSummary. Must be inside ShippingAddressEditController."
-});
-const ShippingAddressCancelButtonDefinition = defineComponent({
-	name: "ShippingAddressCancelButton",
-	importPath: "@vtex/faststore/components",
-	component: ShippingAddressCancelButton,
-	requiresContext: "shipping-address-section",
+	providesContext: "field",
 	editor: {
-		label: "Shipping Address Cancel Button",
+		label: "Country Control",
 		category: "action"
 	},
 	schema: { label: {
 		type: "string",
-		default: "cancelar",
-		label: "Button label"
+		label: "Field label"
 	} },
-	guideline: "Returns the delivery section to its summary without saving. Place it inside a ShippingAddressEditForm so a shopper who opened the form has a way back that does not depend on a successful write. Must be inside ShippingAddressEditController."
+	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."
 });
 /**
-* ShippingAddressRoot owns the batched form state, manages the current descriptor,
-* and provides context to child Controls. It handles submit dispatch and error tracking.
+* ShippingAddressFieldset — this entity's root: same data, same action as a page-level submit
+* would use, dispatched at form-submit time instead of through a button of its own. Registers one
+* `FieldsetRegistration` with the enclosing `FormRoot` under the `shippingAddress` namespace,
+* derives the active country descriptor from react-hook-form (Decision 2), and publishes each
+* field's seed/rule/label through its own context so a bound Control never writes a validation
+* expression. Renders no button and holds no draft of its own.
+*
+* Its controls mount only once the entity has resolved; until then the `Fieldset.Root` carries
+* `-pending` and renders `ShippingAddressFieldsetSkeleton`. "Resolved" is two conditions, because
+* `$data` alone cannot answer it: under the reactive runtime the slice is defined from the first
+* render — `useReactiveEntity` hands down `fallbackData` while the cache read is incomplete — so an
+* empty server answer looks exactly like a resolved one, and every control would mount seeded `''`
+* before the shopper's stored address arrives. Each seed reaches react-hook-form as a field-level
+* `defaultValue`; `useSeedAdoption` re-seeds a clean field with it on every render, but once the
+* field turns dirty no later seed ever reaches it again (Decision 12). Mounting before the answer
+* arrives would seed `''`: a shopper who starts typing before the real value lands makes the field
+* dirty on that empty seed, permanently locking their saved address out of it, and even a shopper who
+* does not type sees the field flash from `''` to the real data. `useReactiveDataSettled` supplies
+* the missing half: the page query's own in-flight state, latched so it only ever goes pending →
+* settled. The `$data === undefined` half still carries
+* trees with no reactive root above them, where the slice arrives as a plain prop.
+*
+* Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a
+* 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 ShippingAddressRoot({ defaultCountry = "BRA", className, children, $data: $dataProp, $actions: $actionsProp }) {
+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 }) {
+	const { registerFieldset } = useFormRegistry();
+	useNoAncestorFieldset("ShippingAddressFieldset");
 	const $data = useDataOverride($dataProp);
 	const $actions = useActionsOverride($actionsProp);
+	const settled = useReactiveDataSettled();
+	const sliceResolved = useEntityDataResolved();
+	const resolved = settled && sliceResolved && $data !== void 0;
 	const currentAddress = $data?.shipping?.address;
-	const savedAddresses = $data?.shipping?.savedAddresses ?? [];
 	const clientProfile = $data?.clientProfile;
 	const joinedProfileName = [clientProfile?.firstName, clientProfile?.lastName].filter(Boolean).join(" ");
-	const seedDraft = useCallback(() => ({
+	const seed = useMemo(() => ({
 		recipientName: currentAddress?.recipientName ?? joinedProfileName,
 		postalCode: currentAddress?.postalCode ?? "",
 		country: currentAddress?.country ?? defaultCountry,
@@ -412,583 +402,306 @@ function ShippingAddressRoot({ defaultCountry = "BRA", className, children, $dat
 		joinedProfileName,
 		defaultCountry
 	]);
-	const [draft, setDraft] = useState(seedDraft);
-	const [submitting, setSubmitting] = useState(false);
-	const [errors, setErrors] = useState([]);
-	const [upstreamError, setUpstreamError] = useState(false);
-	const [selectedSavedId, setSelectedSavedId] = useState();
-	const [savedAddressDrawerOpen, setSavedAddressDrawerOpen] = useState(false);
-	const [drawerSubmitting, setDrawerSubmitting] = useState(false);
-	const [submitSuccessSignal, setSubmitSuccessSignal] = useState(0);
-	const [touchedFields, setTouchedFields] = useState(() => /* @__PURE__ */ new Set());
-	const discardDraft = useCallback(() => {
-		setTouchedFields(/* @__PURE__ */ new Set());
-		setDraft(seedDraft());
-		setErrors([]);
-		setUpstreamError(false);
-	}, [seedDraft]);
-	const currentAddressSnapshot = JSON.stringify(currentAddress ?? null);
-	const clientProfileSnapshot = JSON.stringify(clientProfile ?? null);
-	useEffect(() => {
-		setDraft((prev) => {
-			return {
-				recipientName: touchedFields.has("recipientName") ? prev.recipientName : currentAddress?.recipientName ?? (joinedProfileName || prev.recipientName),
-				postalCode: touchedFields.has("postalCode") ? prev.postalCode : currentAddress?.postalCode ?? prev.postalCode,
-				country: touchedFields.has("country") ? prev.country : currentAddress?.country ?? prev.country,
-				street: touchedFields.has("street") ? prev.street : currentAddress?.street ?? prev.street,
-				number: touchedFields.has("number") ? prev.number : currentAddress?.number ?? prev.number,
-				complement: touchedFields.has("complement") ? prev.complement : currentAddress?.complement ?? prev.complement,
-				neighborhood: touchedFields.has("neighborhood") ? prev.neighborhood : currentAddress?.neighborhood ?? prev.neighborhood,
-				city: touchedFields.has("city") ? prev.city : currentAddress?.city ?? prev.city,
-				state: touchedFields.has("state") ? prev.state : currentAddress?.state ?? prev.state
-			};
-		});
-	}, [
-		currentAddressSnapshot,
-		clientProfileSnapshot,
-		touchedFields
+	const watchedCountry = useWatch({
+		name: `${SHIPPING_ADDRESS_NAMESPACE}.country`,
+		defaultValue: seed.country
+	});
+	const activeCountry = typeof watchedCountry === "string" && watchedCountry || seed.country;
+	const descriptor = getCountryDescriptor(activeCountry);
+	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 field = fieldFor(key);
+		return field ? buildRule(field, label ?? field.label) : void 0;
+	}, [fieldFor]);
+	const countryOptions = useMemo(() => getAvailableCountries().map((iso) => ({
+		value: iso,
+		label: getCountryDescriptor(iso)?.label ?? iso
+	})), []);
+	const fieldsetContextValue = useMemo(() => ({
+		namespace: SHIPPING_ADDRESS_NAMESPACE,
+		descriptor,
+		fieldFor,
+		seedFor,
+		ruleFor,
+		countryOptions
+	}), [
+		descriptor,
+		fieldFor,
+		seedFor,
+		ruleFor,
+		countryOptions
 	]);
-	const currentAddressId = currentAddress?.id ?? void 0;
-	const formattedCurrentAddress = useMemo(() => {
-		if (!currentAddress) return void 0;
+	const { registry: fieldRegistryValue, getFieldNames } = useFieldsetFieldNames(SHIPPING_ADDRESS_NAMESPACE);
+	const toPayload = useCallback((values) => {
+		const merged = {
+			...seed,
+			...pickDefinedAddressFields(values)
+		};
+		const country = String(merged.country || seed.country);
+		const active = getCountryDescriptor(country);
+		const isActive = (key) => active?.fields.some((f) => f.name === key) ?? false;
 		return {
-			recipientName: currentAddress.recipientName ?? "",
-			postalCode: currentAddress.postalCode ?? "",
-			country: currentAddress.country ?? "",
-			street: currentAddress.street ?? "",
-			number: currentAddress.number ?? "",
-			complement: currentAddress.complement ?? "",
-			neighborhood: currentAddress.neighborhood ?? "",
-			city: currentAddress.city ?? "",
-			state: currentAddress.state ?? ""
+			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 } : {}
 		};
-	}, [currentAddress]);
-	const descriptor = getCountryDescriptor(draft.country);
-	const mappedSavedAddresses = useMemo(() => savedAddresses.map((saved) => ({
-		id: saved.id ?? "",
-		address: {
-			recipientName: saved.recipientName ?? "",
-			postalCode: saved.postalCode ?? "",
-			country: saved.country ?? "",
-			street: saved.street ?? "",
-			number: saved.number ?? "",
-			complement: saved.complement ?? "",
-			neighborhood: saved.neighborhood ?? "",
-			city: saved.city ?? "",
-			state: saved.state ?? ""
-		}
-	})), [savedAddresses]);
-	const setDraftField = useCallback((field, value) => {
-		setTouchedFields((prev) => prev.has(field) ? prev : new Set(prev).add(field));
-		setDraft((prev) => ({
-			...prev,
-			[field]: value
-		}));
-	}, []);
-	const selectSavedAddress = useCallback((id) => {
-		setSelectedSavedId(id);
-		if (id) {
-			const saved = mappedSavedAddresses.find((s) => s.id === id);
-			if (saved?.address) {
-				setTouchedFields((prev) => /* @__PURE__ */ new Set([...prev, ...Object.keys(saved.address)]));
-				setDraft((prev) => ({
-					...prev,
-					...saved.address,
-					recipientName: saved.address.recipientName || joinedProfileName
-				}));
-			}
-		}
-	}, [mappedSavedAddresses, joinedProfileName]);
-	const isFormValid = draft.recipientName.trim().length > 0;
-	const handleSubmit = useCallback(async () => {
-		if (!isFormValid || submitting) return;
-		if (!$actions?.shipping?.setAddress) return;
-		setSubmitting(true);
-		setErrors([]);
-		setUpstreamError(false);
-		try {
-			const isFieldActive = (field) => descriptor?.fields.some((f) => f.name === field) ?? false;
-			const addressFields = {
-				recipientName: draft.recipientName.trim(),
-				postalCode: draft.postalCode,
-				country: draft.country,
-				...isFieldActive("street") ? { street: draft.street } : {},
-				...isFieldActive("number") ? { number: draft.number } : {},
-				...isFieldActive("complement") ? { complement: draft.complement } : {},
-				...isFieldActive("neighborhood") ? { neighborhood: draft.neighborhood } : {},
-				...isFieldActive("city") ? { city: draft.city } : {},
-				...isFieldActive("state") ? { state: draft.state } : {}
-			};
-			const input = selectedSavedId ? {
-				savedAddressId: selectedSavedId,
-				...addressFields
-			} : addressFields;
-			const userErrors = await $actions.shipping.setAddress(input);
-			if (userErrors.length === 0) {
-				setErrors([]);
-				setSubmitSuccessSignal((n) => n + 1);
-			} else if (userErrors.some((e) => e.code === "NETWORK_ERROR")) {
-				setErrors([]);
-				setUpstreamError(true);
-			} else setErrors(userErrors);
-		} catch (error) {
-			console.error("[ShippingAddress] setAddress failed:", error);
-			setUpstreamError(true);
-			setErrors([]);
-		} finally {
-			setSubmitting(false);
-		}
-	}, [
-		isFormValid,
-		submitting,
-		$actions?.shipping?.setAddress,
-		draft,
-		selectedSavedId,
-		descriptor
-	]);
-	const handleDrawerSubmit = useCallback(async () => {
-		if (!selectedSavedId) return;
-		if (currentAddressId !== void 0 && selectedSavedId === currentAddressId) {
-			setSavedAddressDrawerOpen(false);
-			return;
-		}
-		const selectedAddress = mappedSavedAddresses.find((s) => s.id === selectedSavedId);
-		if (!selectedAddress) return;
-		if (!selectedAddress.address.recipientName?.trim()) {
-			setSavedAddressDrawerOpen(false);
-			return;
-		}
-		if (!$actions?.shipping?.setAddress) return;
-		setDrawerSubmitting(true);
-		setErrors([]);
-		setUpstreamError(false);
-		try {
-			const input = {
-				savedAddressId: selectedSavedId,
-				recipientName: selectedAddress.address.recipientName || "",
-				postalCode: selectedAddress.address.postalCode || "",
-				country: selectedAddress.address.country || "",
-				street: selectedAddress.address.street || "",
-				number: selectedAddress.address.number || "",
-				complement: selectedAddress.address.complement || "",
-				neighborhood: selectedAddress.address.neighborhood || "",
-				city: selectedAddress.address.city || "",
-				state: selectedAddress.address.state || ""
-			};
-			const userErrors = await $actions.shipping.setAddress(input);
-			if (userErrors.length === 0) {
-				setErrors([]);
-				setSavedAddressDrawerOpen(false);
-				setSubmitSuccessSignal((n) => n + 1);
-			} else if (userErrors.some((e) => e.code === "NETWORK_ERROR")) {
-				setErrors([]);
-				setUpstreamError(true);
-			} else setErrors(userErrors);
-		} catch (error) {
-			console.error("[ShippingAddress] drawer submit failed:", error);
-			setUpstreamError(true);
-			setErrors([]);
-		} finally {
-			setDrawerSubmitting(false);
-		}
-	}, [
-		selectedSavedId,
-		currentAddressId,
-		mappedSavedAddresses,
-		$actions?.shipping?.setAddress
+	}, [seed]);
+	const dispatch = useCallback(async (payload) => {
+		if (!$actions?.shipping?.setAddress) throw new Error("ShippingAddressFieldset requires $actions.shipping.setAddress.");
+		return $actions.shipping.setAddress(payload);
+	}, [$actions]);
+	const registration = useMemo(() => ({
+		namespace: SHIPPING_ADDRESS_NAMESPACE,
+		getFieldNames,
+		dispatch,
+		toPayload,
+		label: "shipping-address"
+	}), [
+		getFieldNames,
+		dispatch,
+		toPayload
 	]);
-	const contextValue = {
-		draft,
-		setDraftField,
-		descriptor,
-		savedAddresses: mappedSavedAddresses,
-		selectedSavedId,
-		setSelectedSavedId: selectSavedAddress,
-		submitting,
-		errors,
-		upstreamError,
-		handleSubmit,
-		currentAddressId,
-		currentAddress: formattedCurrentAddress,
-		submitSuccessSignal,
-		isFormValid,
-		discardDraft
-	};
-	const drawerContextValue = {
-		savedAddressDrawerOpen,
-		setSavedAddressDrawerOpen,
-		drawerSubmitting,
-		handleDrawerSubmit
-	};
-	return /* @__PURE__ */ jsx(ShippingAddressContext.Provider, {
-		value: contextValue,
-		children: /* @__PURE__ */ jsx(ShippingAddressDrawerContext.Provider, {
-			value: drawerContextValue,
-			children: /* @__PURE__ */ jsx("div", {
-				className,
-				"data-fs-shipping-address": "",
-				children
+	useEffect(() => registerFieldset(registration), [registerFieldset, registration]);
+	const [announcement, setAnnouncement] = useState("");
+	const announced = resolved ? loadedLabel : loadingLabel;
+	useEffect(() => {
+		setAnnouncement(announced);
+	}, [announced]);
+	return /* @__PURE__ */ jsxs(Fieldset.Root, {
+		className,
+		"aria-busy": resolved ? void 0 : true,
+		...groupLabel?.trim() ? { "aria-label": groupLabel } : {},
+		"data-fs-shipping-address-fieldset": "",
+		...resolved ? {} : { "data-fs-shipping-address-fieldset-pending": "" },
+		children: [/* @__PURE__ */ jsx(ShippingAddressFieldsetContext.Provider, {
+			value: fieldsetContextValue,
+			children: /* @__PURE__ */ jsx(FieldsetFieldContext.Provider, {
+				value: fieldRegistryValue,
+				children: resolved ? children : /* @__PURE__ */ jsx(ShippingAddressFieldsetSkeleton, { count: skeletonCount })
 			})
+		}), /* @__PURE__ */ jsx("output", {
+			"aria-live": "polite",
+			"data-fs-shipping-address-fieldset-announcement": "",
+			children: announcement
+		})]
+	});
+}
+/**
+* The loading state of the fieldset, rendered in place of the Controls until the entity resolves and
+* declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own
+* live region, so this is hidden from assistive technology rather than announced twice.
+*/
+function ShippingAddressFieldsetSkeleton({ count = SHIPPING_ADDRESS_SKELETON_ROWS, className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className,
+		"data-fs-shipping-address-fieldset-skeleton": "",
+		"aria-hidden": "true",
+		children: Array.from({ length: count }, (_, i) => /* @__PURE__ */ jsx("span", { "data-fs-shipping-address-fieldset-skeleton-field": "" }, i))
+	});
+}
+ShippingAddressFieldset.Skeleton = ShippingAddressFieldsetSkeleton;
+function BoundAddressTextField({ fieldKey, slug, className, label, placeholder, children, fieldsetCtx, fieldDescriptor }) {
+	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, fieldKey);
+	const resolvedLabel = label ?? fieldDescriptor.label;
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label: resolvedLabel,
+		placeholder,
+		defaultValue: fieldsetCtx.seedFor(fieldKey),
+		rule: fieldsetCtx.ruleFor(fieldKey, resolvedLabel),
+		autoComplete: FIELD_AUTOCOMPLETE[fieldKey],
+		children: /* @__PURE__ */ jsx(Field.Root, {
+			className,
+			"data-fs-shipping-address-field": slug,
+			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(Field.Label, {}),
+				/* @__PURE__ */ jsx(Field.Control, {}),
+				/* @__PURE__ */ jsx(Field.Error, {})
+			] })
 		})
 	});
 }
 /**
-* RecipientNameControl — the only client-validated field (US-4, US-6).
+* RecipientNameControl — the only required field (US-4, US-6); the postal code is client-validated
+* too, against the active country's format.
 * Pre-filled from clientProfile, editable, required.
 */
-function ShippingAddressRecipientNameControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	if (!descriptor?.fields.some((f) => f.name === "recipientName")) return null;
-	const label = (descriptor?.fields.find((f) => f.name === "recipientName"))?.label ?? "nome do destinatário";
-	return /* @__PURE__ */ jsxs(Field.Root, {
+function ShippingAddressRecipientNameControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("recipientName");
+	if (!fieldDescriptor) return null;
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "recipientName",
+		slug: "recipient-name",
 		className,
-		"data-fs-shipping-address-field": "recipient-name",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.recipientName,
-			onChange: (e) => setDraftField("recipientName", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** StreetControl */
-function ShippingAddressStreetControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "street");
+function ShippingAddressStreetControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("street");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "street",
+		slug: "street",
 		className,
-		"data-fs-shipping-address-field": "street",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.street,
-			onChange: (e) => setDraftField("street", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** NumberControl */
-function ShippingAddressNumberControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "number");
+function ShippingAddressNumberControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("number");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "number",
+		slug: "number",
 		className,
-		"data-fs-shipping-address-field": "number",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.number,
-			onChange: (e) => setDraftField("number", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** CityControl */
-function ShippingAddressCityControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "city");
+function ShippingAddressCityControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("city");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "city",
+		slug: "city",
 		className,
-		"data-fs-shipping-address-field": "city",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.city,
-			onChange: (e) => setDraftField("city", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** StateControl */
-function ShippingAddressStateControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "state");
+function ShippingAddressStateControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("state");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "state",
+		slug: "state",
 		className,
-		"data-fs-shipping-address-field": "state",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.state,
-			onChange: (e) => setDraftField("state", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** PostalCodeControl */
-function ShippingAddressPostalCodeControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "postalCode");
+function ShippingAddressPostalCodeControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("postalCode");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "postalCode",
+		slug: "postal-code",
 		className,
-		"data-fs-shipping-address-field": "postal-code",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.postalCode,
-			onChange: (e) => setDraftField("postalCode", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** ComplementControl */
-function ShippingAddressComplementControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "complement");
+function ShippingAddressComplementControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("complement");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "complement",
+		slug: "complement",
 		className,
-		"data-fs-shipping-address-field": "complement",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.complement,
-			onChange: (e) => setDraftField("complement", e.currentTarget.value)
-		})]
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /** NeighborhoodControl (BR-specific in v1) */
-function ShippingAddressNeighborhoodControl({ className }) {
-	const { draft, setDraftField, descriptor, submitting } = useShippingAddressContext();
-	const fieldDescriptor = descriptor?.fields.find((f) => f.name === "neighborhood");
+function ShippingAddressNeighborhoodControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	const fieldDescriptor = fieldsetCtx.fieldFor("neighborhood");
 	if (!fieldDescriptor) return null;
-	return /* @__PURE__ */ jsxs(Field.Root, {
-		className,
-		"data-fs-shipping-address-field": "neighborhood",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: fieldDescriptor.label }), /* @__PURE__ */ jsx(Field.Control, {
-			value: draft.neighborhood,
-			onChange: (e) => setDraftField("neighborhood", e.currentTarget.value)
-		})]
-	});
-}
-/** CountryControl — lists only countries with a descriptor (US-2, first criterion) */
-function ShippingAddressCountryControl({ className, label = "país" }) {
-	const { draft, setDraftField, setSelectedSavedId, submitting } = useShippingAddressContext();
-	const countryOptions = getAvailableCountries().map((iso) => {
-		return {
-			value: iso,
-			label: getCountryDescriptor(iso)?.label ?? iso
-		};
-	});
-	const handleCountryChange = (value) => {
-		if (!value) return;
-		if (getCountryDescriptor(value)) {
-			setDraftField("country", value);
-			setSelectedSavedId(void 0);
-		}
-	};
-	return /* @__PURE__ */ jsxs(Field.Root, {
-		className,
-		"data-fs-shipping-address-field": "country",
-		disabled: submitting,
-		children: [/* @__PURE__ */ jsx(Field.Label, { children: label }), /* @__PURE__ */ jsxs(Select.Root, {
-			value: draft.country,
-			onValueChange: handleCountryChange,
-			disabled: submitting,
-			children: [/* @__PURE__ */ jsxs(Select.Trigger, { children: [/* @__PURE__ */ jsx(Select.Value, { children: (value) => value ? getCountryDescriptor(value)?.label ?? value : value }), /* @__PURE__ */ jsx(Select.Icon, { children: "▾" })] }), /* @__PURE__ */ jsx(Select.Portal, { children: /* @__PURE__ */ jsx(Select.Positioner, { children: /* @__PURE__ */ jsx(Select.Popup, { children: /* @__PURE__ */ jsx(Select.List, { children: countryOptions.map((option) => /* @__PURE__ */ jsx(Select.Item, {
-				value: option.value,
-				label: option.label,
-				children: option.label
-			}, option.value)) }) }) }) })]
-		})]
-	});
-}
-/**
-* ShippingAddressSavedList — renders only when savedAddresses is non-empty (logged-in signal).
-*/
-function ShippingAddressSavedList({ className }) {
-	const { savedAddresses } = useShippingAddressContext();
-	if (savedAddresses.length === 0) return null;
-	return /* @__PURE__ */ jsx("div", {
-		className,
-		"data-fs-shipping-address-saved-list": "",
-		children: savedAddresses.map((saved) => /* @__PURE__ */ jsx(ShippingAddressSavedOption, { id: saved.id }, saved.id))
-	});
-}
-/**
-* ShippingAddressSavedOption — selectable saved address; populates draft on selection.
-* Includes isCurrent visual variant to mark the address matching the current cart address (Decision 8).
-*/
-function ShippingAddressSavedOption({ id, className }) {
-	const { savedAddresses, selectedSavedId, setSelectedSavedId, currentAddressId } = useShippingAddressContext();
-	const saved = savedAddresses.find((s) => s.id === id);
-	if (!saved) return null;
-	const isSelected = selectedSavedId === id;
-	const isCurrent = currentAddressId !== void 0 && currentAddressId === id;
-	const hasAddressContent = Boolean(saved.address.recipientName || saved.address.street || saved.address.city || saved.address.neighborhood);
-	const inputId = `saved-address-${id}`;
-	return /* @__PURE__ */ jsxs("div", {
-		className,
-		"data-fs-shipping-address-saved-option": "",
-		...isSelected ? { "data-fs-shipping-address-saved-option-selected": "" } : {},
-		...isCurrent ? { "data-fs-shipping-address-saved-option-current": "" } : {},
-		children: [/* @__PURE__ */ jsx("input", {
-			id: inputId,
-			type: "radio",
-			name: "saved-address",
-			value: id,
-			checked: isSelected,
-			onChange: () => setSelectedSavedId(id)
-		}), /* @__PURE__ */ jsx("label", {
-			htmlFor: inputId,
-			children: hasAddressContent ? /* @__PURE__ */ jsx(AddressSummaryRoot, {
-				address: saved.address,
-				children: /* @__PURE__ */ jsx(AddressSummary, {})
-			}) : `Endereço ${id}`
-		})]
-	});
-}
-/**
-* ShippingAddressSubmit — dispatches the batched submit; reflects pending state.
-*/
-function ShippingAddressSubmit({ className, label = "salvar endereço", pendingLabel = "salvando..." }) {
-	const { submitting, handleSubmit, isFormValid } = useShippingAddressContext();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		onClick: handleSubmit,
-		disabled: submitting || !isFormValid,
+	return /* @__PURE__ */ jsx(BoundAddressTextField, {
+		fieldKey: "neighborhood",
+		slug: "neighborhood",
 		className,
-		"data-fs-shipping-address-submit": "",
-		...submitting ? { "data-fs-shipping-address-submit-pending": "" } : {},
-		children: submitting ? pendingLabel : label
-	});
-}
-/**
-* ShippingAddressSavedAddressDrawerController — makes the wrapped DrawerRoot controlled by the
-* shipping-address context's savedAddressDrawerOpen state, and blocks dismissal (Escape, backdrop
-* click, close button) while drawerSubmitting is true by simply not forwarding the close request
-* to the setter. Mirrors CartOpenOnAdd's cloneElement mechanism. Expects a single DrawerRoot child.
-*/
-function ShippingAddressSavedAddressDrawerController({ children }) {
-	const { savedAddressDrawerOpen, setSavedAddressDrawerOpen, drawerSubmitting } = useShippingAddressDrawerContext();
-	if (!isValidElement(children)) return children;
-	return cloneElement(children, {
-		open: savedAddressDrawerOpen,
-		onOpenChange: (next) => {
-			if (!next && drawerSubmitting) return;
-			setSavedAddressDrawerOpen(next);
-		}
+		label,
+		placeholder,
+		fieldsetCtx,
+		fieldDescriptor,
+		children
 	});
 }
 /**
-* ShippingAddressSavedAddressSubmit — the drawer's "selecionar" submit button; independent
-* submitting state from the main form's Submit (Decision 7); no-ops when the selected saved
-* address is already the current one (Decision 8).
+* 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).
 */
-function ShippingAddressSavedAddressSubmit({ className, label = "selecionar", pendingLabel = "selecionando..." }) {
-	const { selectedSavedId } = useShippingAddressContext();
-	const { drawerSubmitting, handleDrawerSubmit } = useShippingAddressDrawerContext();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		onClick: handleDrawerSubmit,
-		disabled: drawerSubmitting || !selectedSavedId,
+function ShippingAddressCountryControl({ className, label, placeholder, children }) {
+	const fieldsetCtx = useShippingAddressFieldsetContext();
+	if (!fieldsetCtx.descriptor) return null;
+	return /* @__PURE__ */ jsx(BoundShippingAddressCountryControl, {
 		className,
-		"data-fs-shipping-address-saved-address-submit": "",
-		...drawerSubmitting ? { "data-fs-shipping-address-saved-address-submit-pending": "" } : {},
-		children: drawerSubmitting ? pendingLabel : label
+		label,
+		placeholder,
+		fieldsetCtx,
+		children
 	});
 }
-/**
-* ShippingAddressSelectedSummary — provides the current delivery address via AddressSummaryRoot's
-* context and renders it through AddressSummary. Composed lines go through that same wrapper rather
-* than replacing it, because AddressSummaryRoot renders no DOM and `className` would have nowhere to
-* land. Self-gating on currentAddress: renders null when there is none yet, rather than an empty
-* provider with nothing meaningful to show.
-*/
-function ShippingAddressSelectedSummary({ className, children }) {
-	const { currentAddress } = useShippingAddressContext();
-	if (!currentAddress) return null;
-	return /* @__PURE__ */ jsx(AddressSummaryRoot, {
-		address: currentAddress,
-		children: /* @__PURE__ */ jsx(AddressSummary, {
+function BoundShippingAddressCountryControl({ className, label, placeholder, children, fieldsetCtx }) {
+	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, "country");
+	return /* @__PURE__ */ jsx(FieldBinding, {
+		name,
+		label: label ?? "país",
+		placeholder: placeholder ?? fieldsetCtx.descriptor?.label,
+		defaultValue: fieldsetCtx.seedFor("country"),
+		options: fieldsetCtx.countryOptions,
+		autoComplete: FIELD_AUTOCOMPLETE.country,
+		children: /* @__PURE__ */ jsx(Field.Root, {
 			className,
-			children
+			"data-fs-shipping-address-field": "country",
+			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+				/* @__PURE__ */ jsx(Field.Label, {}),
+				/* @__PURE__ */ jsx(FieldSelect.Root, {}),
+				/* @__PURE__ */ jsx(Field.Error, {})
+			] })
 		})
 	});
 }
-/**
-* ShippingAddressEditController — owns the view/edit mode. Defaults to 'view' when a current
-* address exists, 'edit' otherwise (derived reactively from currentAddressId, so it self-corrects
-* if the address arrives asynchronously after mount, same issue as the draft-sync effect above).
-* Once the shopper explicitly toggles (via ShippingAddressEditButton) or a submit succeeds, the
-* explicit mode takes over. Does not render any DOM itself; provides ShippingAddressSectionContext
-* to ShippingAddressSummaryView/ShippingAddressEditForm/ShippingAddressEditButton descendants.
-*/
-function ShippingAddressEditController({ children }) {
-	const { currentAddressId, submitSuccessSignal } = useShippingAddressContext();
-	const [explicitMode, setExplicitMode] = useState(void 0);
-	const lastHandledSignal = useRef(submitSuccessSignal);
-	useEffect(() => {
-		if (submitSuccessSignal !== lastHandledSignal.current) {
-			lastHandledSignal.current = submitSuccessSignal;
-			setExplicitMode("view");
-		}
-	}, [submitSuccessSignal]);
-	const mode = explicitMode ?? (currentAddressId !== void 0 ? "view" : "edit");
-	const modeContextValue = useMemo(() => ({
-		mode,
-		setMode: setExplicitMode
-	}), [mode]);
-	return /* @__PURE__ */ jsx(ShippingAddressSectionContext.Provider, {
-		value: modeContextValue,
-		children
-	});
-}
-/** Renders its children only while the section shows the saved-address summary. */
-function ShippingAddressSummaryView({ children }) {
-	const { mode } = useShippingAddressSectionContext();
-	if (mode !== "view") return null;
-	return /* @__PURE__ */ jsx(Fragment, { children });
-}
-/** Renders its children only while the section shows the address form. */
-function ShippingAddressEditForm({ children }) {
-	const { mode } = useShippingAddressSectionContext();
-	if (mode !== "edit") return null;
-	return /* @__PURE__ */ jsx(Fragment, { children });
-}
-/**
-* ShippingAddressEditButton — CTA that switches the mode to 'edit'. Has no knowledge of why the
-* mode might currently be 'view' (a current address, or a just-completed submit) — it only writes
-* the mode forward.
-*/
-function ShippingAddressEditButton({ className, label = "editar", children }) {
-	const { setMode } = useShippingAddressSectionContext();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		onClick: () => setMode("edit"),
-		className,
-		"data-fs-shipping-address-edit-button": "",
-		children: children ?? label
-	});
-}
-/**
-* ShippingAddressCancelButton — returns the section to its summary without writing. Without it a
-* shopper who opens the form can only leave through a successful `setAddress`, and blanking the
-* recipient disables Submit, which leaves the section stuck open over the summary it replaced.
-*/
-function ShippingAddressCancelButton({ className, label = "cancelar", children }) {
-	const { setMode } = useShippingAddressSectionContext();
-	const { discardDraft } = useShippingAddressContext();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		onClick: () => {
-			discardDraft();
-			setMode("view");
-		},
-		className,
-		"data-fs-shipping-address-cancel-button": "",
-		children: children ?? label
-	});
-}
-/**
-* ShippingAddressError — renders domain userErrors inline, or generic upstream error state.
-*/
-function ShippingAddressError({ className }) {
-	const { errors, upstreamError } = useShippingAddressContext();
-	if (errors.length === 0 && !upstreamError) return null;
-	return /* @__PURE__ */ jsx("div", {
-		className,
-		"data-fs-shipping-address-error": "",
-		children: upstreamError ? /* @__PURE__ */ jsx("div", { children: "Não foi possível salvar este endereço. Revise os dados e tente novamente." }) : /* @__PURE__ */ jsx("ul", { children: errors.map((error, idx) => /* @__PURE__ */ jsx("li", { children: error.message }, idx)) })
-	});
-}
 const ShippingAddress = {
-	Root: ShippingAddressRoot,
-	RootDefinition: ShippingAddressRootDefinition,
+	Fieldset: ShippingAddressFieldset,
+	FieldsetDefinition: ShippingAddressFieldsetDefinition,
+	FieldsetSkeleton: ShippingAddressFieldsetSkeleton,
 	RecipientNameControl: ShippingAddressRecipientNameControl,
 	RecipientNameControlDefinition: ShippingAddressRecipientNameControlDefinition,
 	StreetControl: ShippingAddressStreetControl,
@@ -1006,33 +719,9 @@ const ShippingAddress = {
 	NeighborhoodControl: ShippingAddressNeighborhoodControl,
 	NeighborhoodControlDefinition: ShippingAddressNeighborhoodControlDefinition,
 	CountryControl: ShippingAddressCountryControl,
-	CountryControlDefinition: ShippingAddressCountryControlDefinition,
-	SavedList: ShippingAddressSavedList,
-	SavedListDefinition: ShippingAddressSavedListDefinition,
-	SavedOption: ShippingAddressSavedOption,
-	SavedOptionDefinition: ShippingAddressSavedOptionDefinition,
-	Submit: ShippingAddressSubmit,
-	SubmitDefinition: ShippingAddressSubmitDefinition,
-	SavedAddressDrawerController: ShippingAddressSavedAddressDrawerController,
-	SavedAddressDrawerControllerDefinition: ShippingAddressSavedAddressDrawerControllerDefinition,
-	SavedAddressSubmit: ShippingAddressSavedAddressSubmit,
-	SavedAddressSubmitDefinition: ShippingAddressSavedAddressSubmitDefinition,
-	SelectedSummary: ShippingAddressSelectedSummary,
-	SelectedSummaryDefinition: ShippingAddressSelectedSummaryDefinition,
-	EditController: ShippingAddressEditController,
-	EditControllerDefinition: ShippingAddressEditControllerDefinition,
-	SummaryView: ShippingAddressSummaryView,
-	SummaryViewDefinition: ShippingAddressSummaryViewDefinition,
-	EditForm: ShippingAddressEditForm,
-	EditFormDefinition: ShippingAddressEditFormDefinition,
-	EditButton: ShippingAddressEditButton,
-	EditButtonDefinition: ShippingAddressEditButtonDefinition,
-	CancelButton: ShippingAddressCancelButton,
-	CancelButtonDefinition: ShippingAddressCancelButtonDefinition,
-	Error: ShippingAddressError,
-	ErrorDefinition: ShippingAddressErrorDefinition
+	CountryControlDefinition: ShippingAddressCountryControlDefinition
 };
 //#endregion
-export { ShippingAddress, ShippingAddressCancelButton, ShippingAddressCancelButtonDefinition, ShippingAddressCityControl, ShippingAddressCityControlDefinition, ShippingAddressComplementControl, ShippingAddressComplementControlDefinition, ShippingAddressCountryControl, ShippingAddressCountryControlDefinition, ShippingAddressEditButton, ShippingAddressEditButtonDefinition, ShippingAddressEditController, ShippingAddressEditControllerDefinition, ShippingAddressEditForm, ShippingAddressEditFormDefinition, ShippingAddressError, ShippingAddressErrorDefinition, ShippingAddressNeighborhoodControl, ShippingAddressNeighborhoodControlDefinition, ShippingAddressNumberControl, ShippingAddressNumberControlDefinition, ShippingAddressPostalCodeControl, ShippingAddressPostalCodeControlDefinition, ShippingAddressRecipientNameControl, ShippingAddressRecipientNameControlDefinition, ShippingAddressRoot, ShippingAddressRootDefinition, ShippingAddressSavedAddressDrawerController, ShippingAddressSavedAddressDrawerControllerDefinition, ShippingAddressSavedAddressSubmit, ShippingAddressSavedAddressSubmitDefinition, ShippingAddressSavedList, ShippingAddressSavedListDefinition, ShippingAddressSavedOption, ShippingAddressSavedOptionDefinition, ShippingAddressSelectedSummary, ShippingAddressSelectedSummaryDefinition, ShippingAddressStateControl, ShippingAddressStateControlDefinition, ShippingAddressStreetControl, ShippingAddressStreetControlDefinition, ShippingAddressSubmit, ShippingAddressSubmitDefinition, ShippingAddressSummaryView, ShippingAddressSummaryViewDefinition };
+export { ShippingAddress, ShippingAddressCityControl, ShippingAddressCityControlDefinition, ShippingAddressComplementControl, ShippingAddressComplementControlDefinition, ShippingAddressCountryControl, ShippingAddressCountryControlDefinition, ShippingAddressFieldset, ShippingAddressFieldsetDefinition, ShippingAddressFieldsetSkeleton, ShippingAddressNeighborhoodControl, ShippingAddressNeighborhoodControlDefinition, ShippingAddressNumberControl, ShippingAddressNumberControlDefinition, ShippingAddressPostalCodeControl, ShippingAddressPostalCodeControlDefinition, ShippingAddressRecipientNameControl, ShippingAddressRecipientNameControlDefinition, ShippingAddressStateControl, ShippingAddressStateControlDefinition, ShippingAddressStreetControl, ShippingAddressStreetControlDefinition };
 
 //# sourceMappingURL=shipping-address.js.map