@vtex/faststore 0.0.5 → 0.0.7

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

@@ -1,16 +1,17 @@
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ComponentActions } from "../../sdk/actions/types.js";
-import { ReactNode } from "react";
+import { ComponentPropsWithRef, ReactNode } from "react";
 //#region src/matter/shipping-address/shipping-address.d.ts
 /**
- * The `$data` slice forwarded by the reactive runtime. `ShippingAddressData` selects two root
- * fields (`shipping`, `clientProfile`), so the compiler composes them via
+ * The `$data` slice forwarded to `ShippingAddressFieldset` by the reactive runtime. Selects two
+ * root fields (`shipping`, `clientProfile`), so the compiler composes them via
  * `MultipleReactiveDataProvider`, which keys each entity's resolved slice by its own root field —
  * `$data` is `{ shipping: {...}, clientProfile: {...} }`, not a flat/unwrapped shape (that unwrapped
  * shape only applies to single-root-field fragments, e.g. CartTotalizerRoot's `$data.totalizers`).
+ * Carries no `savedAddresses` — the fieldset has no saved-address UI of its own (Decision 1).
  */
-export type ShippingAddressData = {
+export type ShippingAddressFieldsetData = {
   shipping?: {
     address?: {
       id?: string | null;
@@ -24,106 +25,102 @@ export type ShippingAddressData = {
       city?: string | null;
       state?: string | null;
     } | null;
-    savedAddresses?: Array<{
-      id?: string | null;
-      recipientName?: string | null;
-      postalCode?: string | null;
-      country?: string | null;
-      street?: string | null;
-      number?: string | null;
-      complement?: string | null;
-      neighborhood?: string | null;
-      city?: string | null;
-      state?: string | null;
-    }>;
   } | null;
   clientProfile?: {
     firstName?: string | null;
     lastName?: string | null;
   } | null;
 } | null;
-export type ShippingAddressRootProps = {
-  /** Default country (ISO alpha-3) when no address exists. */
+export type ShippingAddressFieldsetProps = {
+  /** 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;
-  /** `ShippingAddressData` forwarded by the reactive runtime. */
-  $data?: ShippingAddressData;
+  /** `ShippingAddressFieldsetData` forwarded by the reactive runtime. */
+  $data?: ShippingAddressFieldsetData;
   /** Compiler-injected action surface; carries `shipping.setAddress`. */
   $actions?: ComponentActions;
 };
 export type ShippingAddressStreetControlProps = {
   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;
 };
 export type ShippingAddressNumberControlProps = {
   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;
 };
 export type ShippingAddressCityControlProps = {
   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;
 };
 export type ShippingAddressStateControlProps = {
   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;
 };
 export type ShippingAddressPostalCodeControlProps = {
   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;
 };
 export type ShippingAddressComplementControlProps = {
   className?: string;
-};
-export type ShippingAddressNeighborhoodControlProps = {
-  className?: string;
-};
-export type ShippingAddressCountryControlProps = {
-  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;
 };
-export type ShippingAddressRecipientNameControlProps = {
-  className?: string;
-};
-export type ShippingAddressSavedListProps = {
-  className?: string;
-};
-export type ShippingAddressSavedOptionProps = {
-  id: string;
-  className?: string;
-};
-export type ShippingAddressSubmitProps = {
+export type ShippingAddressNeighborhoodControlProps = {
   className?: string;
+  /** Overrides the descriptor's label. Absence means the platform's value. */
   label?: string;
-  pendingLabel?: string;
-};
-export type ShippingAddressErrorProps = {
-  className?: string;
-};
-export type ShippingAddressSavedAddressDrawerControllerProps = {
+  placeholder?: string;
+  /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
 };
-export type ShippingAddressSavedAddressSubmitProps = {
+export type ShippingAddressCountryControlProps = {
   className?: string;
   label?: string;
-  pendingLabel?: string;
-};
-export type ShippingAddressSelectedSummaryProps = {
-  className?: string;
-  /**
-   * The lines to render, in order — typically the `AddressSummaryRecipient` / `Street` / `Locality`
-   * leaves. Defaults to recipient, street, locality when omitted.
-   */
+  placeholder?: string;
+  /** Recomposes the anatomy. Absence renders Field.Label, FieldSelect.Root, Field.Error. */
   children?: ReactNode;
 };
-export type ShippingAddressEditControllerProps = {
-  children?: ReactNode;
-};
-export type ShippingAddressSectionPanelProps = {
-  children?: ReactNode;
-};
-export type ShippingAddressEditButtonProps = {
+export type ShippingAddressRecipientNameControlProps = {
   className?: string;
+  /** Overrides the descriptor's label. Absence means the platform's value. */
   label?: string;
-  /** Compose custom button content (e.g. an Icon plus text); falls back to `label`. */
+  placeholder?: string;
+  /** Recomposes the anatomy. Absence renders Field.Label, Field.Control, Field.Error. */
   children?: ReactNode;
 };
-export declare const ShippingAddressRootDefinition: ComponentDefinition<ShippingAddressRootProps>;
+export declare const ShippingAddressFieldsetDefinition: ComponentDefinition<ShippingAddressFieldsetProps>;
 export declare const ShippingAddressRecipientNameControlDefinition: ComponentDefinition<ShippingAddressRecipientNameControlProps>;
 export declare const ShippingAddressStreetControlDefinition: ComponentDefinition<ShippingAddressStreetControlProps>;
 export declare const ShippingAddressNumberControlDefinition: ComponentDefinition<ShippingAddressNumberControlProps>;
@@ -133,110 +130,76 @@ export declare const ShippingAddressPostalCodeControlDefinition: ComponentDefini
 export declare const ShippingAddressComplementControlDefinition: ComponentDefinition<ShippingAddressComplementControlProps>;
 export declare const ShippingAddressNeighborhoodControlDefinition: ComponentDefinition<ShippingAddressNeighborhoodControlProps>;
 export declare const ShippingAddressCountryControlDefinition: ComponentDefinition<ShippingAddressCountryControlProps>;
-export declare const ShippingAddressSavedListDefinition: ComponentDefinition<ShippingAddressSavedListProps>;
-export declare const ShippingAddressSavedOptionDefinition: ComponentDefinition<ShippingAddressSavedOptionProps>;
-export declare const ShippingAddressSubmitDefinition: ComponentDefinition<ShippingAddressSubmitProps>;
-export declare const ShippingAddressErrorDefinition: ComponentDefinition<ShippingAddressErrorProps>;
-export declare const ShippingAddressSavedAddressDrawerControllerDefinition: ComponentDefinition<ShippingAddressSavedAddressDrawerControllerProps>;
-export declare const ShippingAddressSavedAddressSubmitDefinition: ComponentDefinition<ShippingAddressSavedAddressSubmitProps>;
-export declare const ShippingAddressSelectedSummaryDefinition: ComponentDefinition<ShippingAddressSelectedSummaryProps>;
-export declare const ShippingAddressEditControllerDefinition: ComponentDefinition<ShippingAddressEditControllerProps>;
-export declare const ShippingAddressSummaryViewDefinition: ComponentDefinition<ShippingAddressSectionPanelProps>;
-export declare const ShippingAddressEditFormDefinition: ComponentDefinition<ShippingAddressSectionPanelProps>;
-export declare const ShippingAddressEditButtonDefinition: ComponentDefinition<ShippingAddressEditButtonProps>;
-export declare const ShippingAddressCancelButtonDefinition: ComponentDefinition<ShippingAddressEditButtonProps>;
 /**
- * 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.
  */
-export declare function ShippingAddressRoot({ defaultCountry, className, children, $data: $dataProp, $actions: $actionsProp }: Readonly<ShippingAddressRootProps>): import("react/jsx-runtime").JSX.Element;
+export declare function ShippingAddressFieldset({ defaultCountry, skeletonCount, loadingLabel, loadedLabel, groupLabel, className, children, $data: $dataProp, $actions: $actionsProp }: ShippingAddressFieldsetProps): ReactNode;
+export declare namespace ShippingAddressFieldset {
+  var Skeleton: typeof ShippingAddressFieldsetSkeleton;
+}
 /**
- * RecipientNameControl — the only client-validated field (US-4, US-6).
+ * 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.
+ */
+export declare function ShippingAddressFieldsetSkeleton({ count, className, ...props }: ComponentPropsWithRef<'div'> & {
+  count?: number;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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.
  */
-export declare function ShippingAddressRecipientNameControl({ className }: ShippingAddressRecipientNameControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressRecipientNameControl({ className, label, placeholder, children }: ShippingAddressRecipientNameControlProps): ReactNode;
 /** StreetControl */
-export declare function ShippingAddressStreetControl({ className }: ShippingAddressStreetControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressStreetControl({ className, label, placeholder, children }: ShippingAddressStreetControlProps): ReactNode;
 /** NumberControl */
-export declare function ShippingAddressNumberControl({ className }: ShippingAddressNumberControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressNumberControl({ className, label, placeholder, children }: ShippingAddressNumberControlProps): ReactNode;
 /** CityControl */
-export declare function ShippingAddressCityControl({ className }: ShippingAddressCityControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressCityControl({ className, label, placeholder, children }: ShippingAddressCityControlProps): ReactNode;
 /** StateControl */
-export declare function ShippingAddressStateControl({ className }: ShippingAddressStateControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressStateControl({ className, label, placeholder, children }: ShippingAddressStateControlProps): ReactNode;
 /** PostalCodeControl */
-export declare function ShippingAddressPostalCodeControl({ className }: ShippingAddressPostalCodeControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressPostalCodeControl({ className, label, placeholder, children }: ShippingAddressPostalCodeControlProps): ReactNode;
 /** ComplementControl */
-export declare function ShippingAddressComplementControl({ className }: ShippingAddressComplementControlProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressComplementControl({ className, label, placeholder, children }: ShippingAddressComplementControlProps): ReactNode;
 /** NeighborhoodControl (BR-specific in v1) */
-export declare function ShippingAddressNeighborhoodControl({ className }: ShippingAddressNeighborhoodControlProps): import("react/jsx-runtime").JSX.Element | null;
-/** CountryControl — lists only countries with a descriptor (US-2, first criterion) */
-export declare function ShippingAddressCountryControl({ className, label }: ShippingAddressCountryControlProps): import("react/jsx-runtime").JSX.Element;
-/**
- * ShippingAddressSavedList — renders only when savedAddresses is non-empty (logged-in signal).
- */
-export declare function ShippingAddressSavedList({ className }: ShippingAddressSavedListProps): import("react/jsx-runtime").JSX.Element | null;
-/**
- * ShippingAddressSavedOption — selectable saved address; populates draft on selection.
- * Includes isCurrent visual variant to mark the address matching the current cart address (Decision 8).
- */
-export declare function ShippingAddressSavedOption({ id, className }: ShippingAddressSavedOptionProps): import("react/jsx-runtime").JSX.Element | null;
-/**
- * ShippingAddressSubmit — dispatches the batched submit; reflects pending state.
- */
-export declare function ShippingAddressSubmit({ className, label, pendingLabel }: ShippingAddressSubmitProps): import("react/jsx-runtime").JSX.Element;
-/**
- * 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.
- */
-export declare function ShippingAddressSavedAddressDrawerController({ children }: ShippingAddressSavedAddressDrawerControllerProps): ReactNode;
-/**
- * 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).
- */
-export declare function ShippingAddressSavedAddressSubmit({ className, label, pendingLabel }: ShippingAddressSavedAddressSubmitProps): import("react/jsx-runtime").JSX.Element;
-/**
- * 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.
- */
-export declare function ShippingAddressSelectedSummary({ className, children }: ShippingAddressSelectedSummaryProps): import("react/jsx-runtime").JSX.Element | null;
-/**
- * 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.
- */
-export declare function ShippingAddressEditController({ children }: ShippingAddressEditControllerProps): import("react/jsx-runtime").JSX.Element;
-/** Renders its children only while the section shows the saved-address summary. */
-export declare function ShippingAddressSummaryView({ children }: ShippingAddressSectionPanelProps): import("react/jsx-runtime").JSX.Element | null;
-/** Renders its children only while the section shows the address form. */
-export declare function ShippingAddressEditForm({ children }: ShippingAddressSectionPanelProps): import("react/jsx-runtime").JSX.Element | null;
-/**
- * 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.
- */
-export declare function ShippingAddressEditButton({ className, label, children }: ShippingAddressEditButtonProps): import("react/jsx-runtime").JSX.Element;
-/**
- * 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.
- */
-export declare function ShippingAddressCancelButton({ className, label, children }: ShippingAddressEditButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function ShippingAddressNeighborhoodControl({ className, label, placeholder, children }: ShippingAddressNeighborhoodControlProps): ReactNode;
 /**
- * ShippingAddressError — renders domain userErrors inline, or generic upstream error state.
+ * 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 ShippingAddressError({ className }: ShippingAddressErrorProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ShippingAddressCountryControl({ className, label, placeholder, children }: ShippingAddressCountryControlProps): ReactNode;
 export declare const ShippingAddress: {
-  Root: typeof ShippingAddressRoot;
-  RootDefinition: ComponentDefinition<ShippingAddressRootProps>;
+  Fieldset: typeof ShippingAddressFieldset;
+  FieldsetDefinition: ComponentDefinition<ShippingAddressFieldsetProps>;
+  FieldsetSkeleton: typeof ShippingAddressFieldsetSkeleton;
   RecipientNameControl: typeof ShippingAddressRecipientNameControl;
   RecipientNameControlDefinition: ComponentDefinition<ShippingAddressRecipientNameControlProps>;
   StreetControl: typeof ShippingAddressStreetControl;
@@ -255,30 +218,6 @@ export declare const ShippingAddress: {
   NeighborhoodControlDefinition: ComponentDefinition<ShippingAddressNeighborhoodControlProps>;
   CountryControl: typeof ShippingAddressCountryControl;
   CountryControlDefinition: ComponentDefinition<ShippingAddressCountryControlProps>;
-  SavedList: typeof ShippingAddressSavedList;
-  SavedListDefinition: ComponentDefinition<ShippingAddressSavedListProps>;
-  SavedOption: typeof ShippingAddressSavedOption;
-  SavedOptionDefinition: ComponentDefinition<ShippingAddressSavedOptionProps>;
-  Submit: typeof ShippingAddressSubmit;
-  SubmitDefinition: ComponentDefinition<ShippingAddressSubmitProps>;
-  SavedAddressDrawerController: typeof ShippingAddressSavedAddressDrawerController;
-  SavedAddressDrawerControllerDefinition: ComponentDefinition<ShippingAddressSavedAddressDrawerControllerProps>;
-  SavedAddressSubmit: typeof ShippingAddressSavedAddressSubmit;
-  SavedAddressSubmitDefinition: ComponentDefinition<ShippingAddressSavedAddressSubmitProps>;
-  SelectedSummary: typeof ShippingAddressSelectedSummary;
-  SelectedSummaryDefinition: ComponentDefinition<ShippingAddressSelectedSummaryProps>;
-  EditController: typeof ShippingAddressEditController;
-  EditControllerDefinition: ComponentDefinition<ShippingAddressEditControllerProps>;
-  SummaryView: typeof ShippingAddressSummaryView;
-  SummaryViewDefinition: ComponentDefinition<ShippingAddressSectionPanelProps>;
-  EditForm: typeof ShippingAddressEditForm;
-  EditFormDefinition: ComponentDefinition<ShippingAddressSectionPanelProps>;
-  EditButton: typeof ShippingAddressEditButton;
-  EditButtonDefinition: ComponentDefinition<ShippingAddressEditButtonProps>;
-  CancelButton: typeof ShippingAddressCancelButton;
-  CancelButtonDefinition: ComponentDefinition<ShippingAddressEditButtonProps>;
-  Error: typeof ShippingAddressError;
-  ErrorDefinition: ComponentDefinition<ShippingAddressErrorProps>;
 };
 //#endregion
 //# sourceMappingURL=shipping-address.d.ts.map