@asteby/storefront-react 0.26.0 → 0.28.0

package/dist/checkout.d.cts

@@ -18,6 +18,8 @@ type AddressFieldsMessages = Record<AddressFieldKey | ContactFieldKey, string> &
     provinceLocked: string;
     /** Discreet action that releases the locked state so the buyer can fix the postal code. */
     changePostalCode: string;
+    /** Visually hidden prefix of the one-line place summary (what a screen reader hears before "Miguel Hidalgo, Ciudad de México"). */
+    resolvedPlace: string;
 };
 declare function addressFieldsMessages(locale?: string | null, overrides?: Partial<AddressFieldsMessages> | null): AddressFieldsMessages;
 type FieldLayoutClassNames = CheckoutFieldClassNames & {
@@ -54,11 +56,21 @@ type PostalCodeInfo = {
     province?: string | null;
     city?: string | null;
     neighborhoods?: readonly string[] | null;
+    /**
+     * Every municipality the code covers, when the catalog knows more than one. With two or more the code is ambiguous:
+     * `hideResolvedFields` keeps the city field editable instead of choosing for the buyer.
+     */
+    cities?: readonly string[] | null;
+    /**
+     * Municipality to SHOW in the one-line summary (`hideResolvedFields`) when it differs from `city`, the value that is
+     * submitted (and may feed the delivery quote). Display only: never sent.
+     */
+    municipality?: string | null;
 };
 type AddressFieldsProps = Common & {
     defaults?: Partial<Pick<Address, 'zip' | 'province' | 'city' | 'neighborhood' | 'address1' | 'address2' | 'reference'>> | null;
     /** Form names. Default: the keys (the `AddressInput` fields of the Storefront API). */
-    names?: Partial<Record<AddressFieldKey, string>>;
+    names?: Partial<Record<AddressFieldKey | 'province_code', string>>;
     /** ISO country of the address (hidden field `country_code`). */
     countryCode: string;
     /** States of the country (from the region config). With them, "State" is a `<select>`; the value sent is `name`. */
@@ -99,6 +111,17 @@ type AddressFieldsProps = Common & {
      * `data-sf-locked="1"` for the shop's own styling.
      */
     lockProvinceOnFill?: boolean;
+    /**
+     * When the postal-code lookup resolves BOTH state and city/municipality (and the catalog does not return several
+     * municipalities), they are not shown as inputs: one read-only line under the postal code ("Miguel Hidalgo, Ciudad de
+     * México" plus a discreet `changePostalCode` link) and the values travel in hidden fields with the usual names
+     * (`province`, `province_code` when the `provinces` list knows it, `city`), so the server still validates state against
+     * postal code. If the code resolves nothing, is unknown, the lookup fails, the municipality is ambiguous, the state is
+     * not in `provinces`, the buyer already typed a different value, or the server reports an error on state/city, the
+     * inputs are shown editable (the buyer can always complete the address). Without JavaScript the form is the plain
+     * inputs. Default TRUE; `false` keeps the previous behavior (inputs filled, state locked per `lockProvinceOnFill`).
+     */
+    hideResolvedFields?: boolean;
     /** Rendered after the fields (e.g. "save this address"). */
     children?: ReactNode;
 };

package/dist/checkout.d.ts

@@ -18,6 +18,8 @@ type AddressFieldsMessages = Record<AddressFieldKey | ContactFieldKey, string> &
     provinceLocked: string;
     /** Discreet action that releases the locked state so the buyer can fix the postal code. */
     changePostalCode: string;
+    /** Visually hidden prefix of the one-line place summary (what a screen reader hears before "Miguel Hidalgo, Ciudad de México"). */
+    resolvedPlace: string;
 };
 declare function addressFieldsMessages(locale?: string | null, overrides?: Partial<AddressFieldsMessages> | null): AddressFieldsMessages;
 type FieldLayoutClassNames = CheckoutFieldClassNames & {
@@ -54,11 +56,21 @@ type PostalCodeInfo = {
     province?: string | null;
     city?: string | null;
     neighborhoods?: readonly string[] | null;
+    /**
+     * Every municipality the code covers, when the catalog knows more than one. With two or more the code is ambiguous:
+     * `hideResolvedFields` keeps the city field editable instead of choosing for the buyer.
+     */
+    cities?: readonly string[] | null;
+    /**
+     * Municipality to SHOW in the one-line summary (`hideResolvedFields`) when it differs from `city`, the value that is
+     * submitted (and may feed the delivery quote). Display only: never sent.
+     */
+    municipality?: string | null;
 };
 type AddressFieldsProps = Common & {
     defaults?: Partial<Pick<Address, 'zip' | 'province' | 'city' | 'neighborhood' | 'address1' | 'address2' | 'reference'>> | null;
     /** Form names. Default: the keys (the `AddressInput` fields of the Storefront API). */
-    names?: Partial<Record<AddressFieldKey, string>>;
+    names?: Partial<Record<AddressFieldKey | 'province_code', string>>;
     /** ISO country of the address (hidden field `country_code`). */
     countryCode: string;
     /** States of the country (from the region config). With them, "State" is a `<select>`; the value sent is `name`. */
@@ -99,6 +111,17 @@ type AddressFieldsProps = Common & {
      * `data-sf-locked="1"` for the shop's own styling.
      */
     lockProvinceOnFill?: boolean;
+    /**
+     * When the postal-code lookup resolves BOTH state and city/municipality (and the catalog does not return several
+     * municipalities), they are not shown as inputs: one read-only line under the postal code ("Miguel Hidalgo, Ciudad de
+     * México" plus a discreet `changePostalCode` link) and the values travel in hidden fields with the usual names
+     * (`province`, `province_code` when the `provinces` list knows it, `city`), so the server still validates state against
+     * postal code. If the code resolves nothing, is unknown, the lookup fails, the municipality is ambiguous, the state is
+     * not in `provinces`, the buyer already typed a different value, or the server reports an error on state/city, the
+     * inputs are shown editable (the buyer can always complete the address). Without JavaScript the form is the plain
+     * inputs. Default TRUE; `false` keeps the previous behavior (inputs filled, state locked per `lockProvinceOnFill`).
+     */
+    hideResolvedFields?: boolean;
     /** Rendered after the fields (e.g. "save this address"). */
     children?: ReactNode;
 };

package/dist/checkout.js

@@ -30,7 +30,8 @@ var ES = {
   phoneHint: "Solo para la paqueter\xEDa, por si necesita contactarte.",
   lookupFilled: "Completamos estado y ciudad con tu c\xF3digo postal.",
   provinceLocked: "Definido por tu c\xF3digo postal",
-  changePostalCode: "Cambiar c\xF3digo postal"
+  changePostalCode: "Cambiar c\xF3digo postal",
+  resolvedPlace: "Entrega en"
 };
 var EN = {
   email: "Email",
@@ -52,7 +53,8 @@ var EN = {
   phoneHint: "Only for the carrier, in case they need to reach you.",
   lookupFilled: "We filled in state and city from your postal code.",
   provinceLocked: "Set by your postal code",
-  changePostalCode: "Change postal code"
+  changePostalCode: "Change postal code",
+  resolvedPlace: "Delivering to"
 };
 function addressFieldsMessages(locale, overrides) {
   const base = (locale ?? "es-MX").toLowerCase().startsWith("en") ? EN : ES;
@@ -111,8 +113,11 @@ var ADDRESS_FILL_EVENT_FLAG = "sfSynthetic";
 function isAddressFillEvent(event) {
   return event[ADDRESS_FILL_EVENT_FLAG] === true;
 }
+var SR_ONLY = { position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" };
+var sameText = (a, b) => fold(a) === fold(b);
+var fold = (v) => v.normalize("NFD").replace(/[\u0300-\u036f]/g, "").trim().toLowerCase();
 function AddressFields(props) {
-  const { defaults, names = {}, errors = {}, countryCode, provinces, postalCode, lookupPostalCode, lockProvinceOnFill = true, locale, messages, fieldMessages: fm, classNames: cx = {}, children } = props;
+  const { defaults, names = {}, errors = {}, countryCode, provinces, postalCode, lookupPostalCode, lockProvinceOnFill = true, hideResolvedFields = true, locale, messages, fieldMessages: fm, classNames: cx = {}, children } = props;
   const showNeighborhood = props.neighborhood ?? true;
   const showReference = props.reference ?? true;
   const m = addressFieldsMessages(locale, messages);
@@ -123,6 +128,9 @@ function AddressFields(props) {
   const [filled, setFilled] = useState(false);
   const [provinceLocked, setProvinceLocked] = useState(false);
   const [coloniaSelect, setColoniaSelect] = useState(false);
+  const [resolved, setResolved] = useState(null);
+  const resolvedRef = useRef(false);
+  const [defaultsStale, setDefaultsStale] = useState(false);
   const coloniaSelectRef = useRef(false);
   const coloniaCarry = useRef(null);
   const lastZip = useRef(null);
@@ -157,6 +165,7 @@ function AddressFields(props) {
     if (!form) return;
     const locked = form.querySelector('[data-sf-locked="1"]');
     const touched = [];
+    if (resolvedRef.current) setDefaultsStale(true);
     if (locked) {
       unlockField(locked);
       touched.push(locked);
@@ -174,9 +183,32 @@ function AddressFields(props) {
       el.dispatchEvent(event);
     }
     lastZip.current = null;
+    resolvedRef.current = false;
+    setResolved(null);
     setProvinceLocked(false);
     setFilled(false);
   };
+  const resolveHidden = (info, form) => {
+    if (!form || !info.province || !info.city) return null;
+    if ((info.cities?.length ?? 0) > 1) return null;
+    let province = info.province.trim();
+    let provinceCode = null;
+    if (provinces && provinces.length) {
+      const hit = provinces.find((p) => sameText(p.name, province) || !!p.code && sameText(p.code, province));
+      if (!hit) return null;
+      province = hit.name;
+      provinceCode = hit.code ?? null;
+    }
+    const city = info.city.trim();
+    if (!province || !city) return null;
+    const theirs = (name, value) => {
+      const el = form.elements.namedItem(name);
+      if (!el || "length" in el && !(el instanceof HTMLSelectElement)) return false;
+      return !!el.value && el.dataset.sfAutofilled !== "1" && !sameText(el.value, value);
+    };
+    if (theirs(n("province"), province) || theirs(n("city"), city)) return null;
+    return { province, provinceCode, city, place: info.municipality?.trim() || city };
+  };
   const runLookup = (zip) => {
     const lookup = lookupRef.current;
     if (!lookup || !zip || zip === lastZip.current) return;
@@ -207,8 +239,14 @@ function AddressFields(props) {
             }
             return true;
           };
-          const a = fill2(n("province"), info.province, lockProvinceOnFill);
-          const b = fill2(n("city"), info.city);
+          const resolution = hideResolvedFields ? resolveHidden(info, form) : null;
+          if (resolution) {
+            resolvedRef.current = true;
+            setDefaultsStale(true);
+            setResolved(resolution);
+          }
+          const a = resolution ? false : fill2(n("province"), info.province, lockProvinceOnFill);
+          const b = resolution ? false : fill2(n("city"), info.city);
           const only = info.neighborhoods?.length === 1 ? info.neighborhoods[0] : null;
           const c = showNeighborhood ? fill2(n("neighborhood"), only) : false;
           setColonias(info.neighborhoods ?? []);
@@ -226,7 +264,7 @@ function AddressFields(props) {
           }
           coloniaSelectRef.current = wantSelect;
           setColoniaSelect(wantSelect);
-          setFilled(a || b || c || carried);
+          setFilled(!resolution && (a || b || c || carried));
         });
       },
       () => {
@@ -252,7 +290,20 @@ function AddressFields(props) {
     const zip = defaults?.zip;
     if (zip) runLookup(zip);
   }, []);
-  const hasLock = (root) => !!root?.closest("form")?.querySelector('[data-sf-locked="1"]');
+  const firstRender = useRef(true);
+  useEffect(() => {
+    if (firstRender.current) {
+      firstRender.current = false;
+      return;
+    }
+    const form = zipRef.current?.closest("form");
+    const el = (resolved ? form?.querySelector('input[type="hidden"][data-sf-resolved-field="city"]') : null) ?? zipRef.current?.querySelector("input");
+    if (!el) return;
+    const event = new Event("input", { bubbles: true });
+    Object.defineProperty(event, ADDRESS_FILL_EVENT_FLAG, { value: true });
+    el.dispatchEvent(event);
+  }, [resolved]);
+  const hasLock = (root) => resolvedRef.current || !!root?.closest("form")?.querySelector('[data-sf-locked="1"]');
   const changeZip = () => {
     releaseLookup();
     const zipEl = zipRef.current?.querySelector("input");
@@ -269,35 +320,61 @@ function AddressFields(props) {
     /* @__PURE__ */ jsx("button", { type: "button", "data-sf-change-zip": "", onClick: changeZip, style: { background: "none", border: 0, padding: 0, font: "inherit", color: "inherit", textDecoration: "underline", cursor: "pointer" }, children: m.changePostalCode })
   ] }) : void 0;
   const numericZip = postalCode?.inputMode === "numeric";
+  const showResolved = !!resolved && !errors[n("province")] && !errors[n("city")];
+  const startOf = (key) => resolved ? resolved[key] : defaultsStale ? "" : defaults?.[key] ?? "";
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsx("div", { ref: zipRef, className: join(cx.half), "data-sf-zip": true, children: /* @__PURE__ */ jsx(
-      CheckoutField,
-      {
-        ...common,
-        name: n("zip"),
-        label: m.zip,
-        autoComplete: "postal-code",
-        inputMode: postalCode?.inputMode ?? "text",
-        ...postalCode?.pattern ? { pattern: postalCode.pattern } : {},
-        ...postalCode?.maxLength ? { maxLength: postalCode.maxLength } : {},
-        ...postalCode?.title ? { title: postalCode.title } : {},
-        ...numericZip ? { autoCapitalize: "none" } : {},
-        defaultValue: defaults?.zip ?? "",
-        error: errors[n("zip")] ?? null,
-        classNames: { ...cx, root: cx.root },
-        onInput: (e) => {
-          const v = e.currentTarget.value.trim();
-          if (v !== lastZip.current && hasLock(zipRef.current)) releaseLookup();
-          if (postalCode?.maxLength && v.length === postalCode.maxLength) runLookup(v);
-        },
-        onBlur: (e) => runLookup(e.currentTarget.value.trim())
-      }
-    ) }),
-    provinces && provinces.length ? /* @__PURE__ */ jsxs(CheckoutField, { ...common, as: "select", name: n("province"), label: m.province, autoComplete: "address-level1", defaultValue: defaults?.province ?? "", error: errors[n("province")] ?? null, classNames: field(cx, "half"), hint: provinceHint, children: [
+    /* @__PURE__ */ jsxs("div", { ref: zipRef, className: join(cx.half), "data-sf-zip": true, children: [
+      /* @__PURE__ */ jsx(
+        CheckoutField,
+        {
+          ...common,
+          name: n("zip"),
+          label: m.zip,
+          autoComplete: "postal-code",
+          inputMode: postalCode?.inputMode ?? "text",
+          ...postalCode?.pattern ? { pattern: postalCode.pattern } : {},
+          ...postalCode?.maxLength ? { maxLength: postalCode.maxLength } : {},
+          ...postalCode?.title ? { title: postalCode.title } : {},
+          ...numericZip ? { autoCapitalize: "none" } : {},
+          defaultValue: defaults?.zip ?? "",
+          error: errors[n("zip")] ?? null,
+          classNames: { ...cx, root: cx.root },
+          onInput: (e) => {
+            const v = e.currentTarget.value.trim();
+            if (v !== lastZip.current && hasLock(zipRef.current)) releaseLookup();
+            if (postalCode?.maxLength && v.length === postalCode.maxLength) runLookup(v);
+          },
+          onBlur: (e) => runLookup(e.currentTarget.value.trim())
+        }
+      ),
+      /* @__PURE__ */ jsxs("div", { "data-sf-resolved": showResolved ? "" : void 0, className: showResolved || filled ? join(cx.hint) : void 0, children: [
+        /* @__PURE__ */ jsx("p", { role: "status", "aria-live": "polite", "data-sf-zip-status": true, style: showResolved || filled ? showResolved ? { display: "inline", margin: 0 } : void 0 : SR_ONLY, children: showResolved && resolved ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs("span", { style: SR_ONLY, children: [
+            m.resolvedPlace,
+            " "
+          ] }),
+          /* @__PURE__ */ jsxs("span", { "data-sf-resolved-place": true, children: [
+            resolved.place,
+            ", ",
+            resolved.province
+          ] })
+        ] }) : filled ? m.lookupFilled : "" }),
+        showResolved ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          " \xB7 ",
+          /* @__PURE__ */ jsx("button", { type: "button", "data-sf-change-zip": "", onClick: changeZip, style: { background: "none", border: 0, padding: 0, font: "inherit", color: "inherit", textDecoration: "underline", cursor: "pointer" }, children: m.changePostalCode })
+        ] }) : null
+      ] })
+    ] }),
+    showResolved && resolved ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("input", { type: "hidden", name: n("province"), value: resolved.province, "data-sf-resolved-field": "province" }),
+      resolved.provinceCode ? /* @__PURE__ */ jsx("input", { type: "hidden", name: n("province_code"), value: resolved.provinceCode, "data-sf-resolved-field": "province_code" }) : null,
+      /* @__PURE__ */ jsx("input", { type: "hidden", name: n("city"), value: resolved.city, "data-sf-resolved-field": "city" })
+    ] }) : null,
+    showResolved ? null : provinces && provinces.length ? /* @__PURE__ */ jsxs(CheckoutField, { ...common, as: "select", name: n("province"), label: m.province, autoComplete: "address-level1", defaultValue: startOf("province"), error: errors[n("province")] ?? null, classNames: field(cx, "half"), hint: provinceHint, children: [
       /* @__PURE__ */ jsx("option", { value: "", disabled: true, children: m.provincePlaceholder }),
       provinces.map((p) => /* @__PURE__ */ jsx("option", { value: p.name, children: p.name }, p.code ?? p.name))
-    ] }) : /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("province"), label: m.province, autoComplete: "address-level1", defaultValue: defaults?.province ?? "", error: errors[n("province")] ?? null, classNames: field(cx, "half"), hint: provinceHint }),
-    /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("city"), label: m.city, autoComplete: "address-level2", defaultValue: defaults?.city ?? "", error: errors[n("city")] ?? null, classNames: field(cx, "half") }),
+    ] }) : /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("province"), label: m.province, autoComplete: "address-level1", defaultValue: startOf("province"), error: errors[n("province")] ?? null, classNames: field(cx, "half"), hint: provinceHint }),
+    showResolved ? null : /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("city"), label: m.city, autoComplete: "address-level2", defaultValue: startOf("city"), error: errors[n("city")] ?? null, classNames: field(cx, "half") }),
     showNeighborhood && coloniaSelect ? /* @__PURE__ */ jsxs(
       CheckoutField,
       {
@@ -330,7 +407,6 @@ function AddressFields(props) {
       }
     ) : null,
     colonias.length && !coloniaSelect ? /* @__PURE__ */ jsx("datalist", { id: listId, children: colonias.map((c) => /* @__PURE__ */ jsx("option", { value: c }, c)) }) : null,
-    /* @__PURE__ */ jsx("p", { role: "status", "aria-live": "polite", "data-sf-zip-status": true, style: filled ? void 0 : { position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" }, className: filled ? join(cx.hint, cx.wide) : void 0, children: filled ? m.lookupFilled : "" }),
     /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("address1"), label: m.address1, autoComplete: "address-line1", defaultValue: defaults?.address1 ?? "", error: errors[n("address1")] ?? null, hint: m.address1Hint, classNames: field(cx, "wide") }),
     /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("address2"), label: m.address2, autoComplete: "address-line2", optional: true, defaultValue: defaults?.address2 ?? "", error: errors[n("address2")] ?? null, classNames: field(cx, "half") }),
     showReference ? /* @__PURE__ */ jsx(CheckoutField, { ...common, name: n("reference"), label: m.reference, optional: true, defaultValue: defaults?.reference ?? "", error: errors[n("reference")] ?? null, hint: m.referenceHint, classNames: field(cx, "wide"), maxLength: 200 }) : null,
@@ -693,7 +769,7 @@ function matchRate(previous, rates) {
   }
   return rates.find((r) => sameCarrier(r) && norm3(r.title) === norm3(previous.title)) ?? null;
 }
-var SR_ONLY = { position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" };
+var SR_ONLY2 = { position: "absolute", width: 1, height: 1, overflow: "hidden", clip: "rect(0 0 0 0)", whiteSpace: "nowrap" };
 var useHydrated = () => useSyncExternalStore(
   () => () => {
   },
@@ -780,7 +856,7 @@ function DeliveryOptions(props) {
       ) : null,
       /* @__PURE__ */ jsxs("span", { className: cx.body, "data-sf-delivery-body": true, children: [
         /* @__PURE__ */ jsx("span", { className: cx.title, "data-sf-delivery-title": true, children: carrier ? opts.grouped ? /* @__PURE__ */ jsxs(Fragment, { children: [
-          /* @__PURE__ */ jsxs("span", { style: SR_ONLY, children: [
+          /* @__PURE__ */ jsxs("span", { style: SR_ONLY2, children: [
             carrier,
             " "
           ] }),
@@ -801,8 +877,8 @@ function DeliveryOptions(props) {
   return /* @__PURE__ */ jsxs("div", { className: cx.root, "data-sf-delivery": true, "data-layout": layout, "aria-busy": loading || void 0, children: [
     partial && !errorText ? /* @__PURE__ */ jsx("p", { role: "status", className: cx.partial, "data-sf-delivery-partial": true, children: m.partial }) : null,
     requoted ? /* @__PURE__ */ jsx("p", { role: "status", className: cx.partial, "data-sf-delivery-requoted": true, children: m.requoted }) : null,
-    loading ? /* @__PURE__ */ jsx("span", { style: SR_ONLY, role: "status", "data-sf-delivery-loading": true, children: m.loading }) : null,
-    props.announceReady && !loading && rates.length > 0 ? /* @__PURE__ */ jsx("span", { style: SR_ONLY, role: "status", "data-sf-delivery-ready": true, children: freeRate ? m.freeShipping : m.ratesReady.replace("{n}", String(rates.length)) }) : null,
+    loading ? /* @__PURE__ */ jsx("span", { style: SR_ONLY2, role: "status", "data-sf-delivery-loading": true, children: m.loading }) : null,
+    props.announceReady && !loading && rates.length > 0 ? /* @__PURE__ */ jsx("span", { style: SR_ONLY2, role: "status", "data-sf-delivery-ready": true, children: freeRate ? m.freeShipping : m.ratesReady.replace("{n}", String(rates.length)) }) : null,
     errorText && rates.length === 0 && !loading ? /* @__PURE__ */ jsxs("div", { role: "alert", className: cx.error, "data-sf-delivery-error": true, children: [
       /* @__PURE__ */ jsx("p", { children: errorText }),
       onRetry ? /* @__PURE__ */ jsx("button", { type: "button", className: cx.retry, onClick: onRetry, "data-sf-delivery-retry": true, children: m.retry }) : null