@ikeboy003/address 0.1.1

package/README.md

@@ -0,0 +1,42 @@
+# @ikeboy003/address
+
+Headless Google Places address autocomplete. One public, referrer-restricted browser
+key serves every site — no backend, no D1 cache (the JS widget is session-billed in
+the browser and Google's ToS forbids storing predictions).
+
+Over a raw autocomplete it returns **structured, ShipTo-shaped parts** so a checkout
+form auto-fills street/city/state/zip instead of just a display string.
+
+## Setup
+
+Set `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` (or `configureAddress({ apiKey })`). Restrict the
+key to your domains + the Maps JavaScript API + Places library in the Google console.
+
+## Hook (headless — you own the input)
+
+```tsx
+import { useAddressAutocomplete } from "@ikeboy003/address/react";
+
+const { inputRef, error } = useAddressAutocomplete({
+  onSelect: (r) => setShip((s) => ({ ...s, ...r.parts })), // parts ⊂ ShipTo
+});
+
+<input ref={inputRef} placeholder="Start typing your address…" className={inputCls} />
+```
+
+## Component
+
+```tsx
+import { AddressAutocomplete } from "@ikeboy003/address/react";
+
+<AddressAutocomplete
+  className={inputCls}
+  placeholder="Street address"
+  onSelect={(r) => setShip((s) => ({ ...s, ...r.parts }))}
+  onRawChange={(v) => setStreet1(v)}
+/>
+```
+
+`AddressResult`: `{ formatted, parts: { street1, street2, city, state, postal, country }, placeId }`.
+
+`placeId` is the only Google field allowed to be persisted long-term.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { configureAddress, loadPlaces, addressCountry } from "./loader";
+export { parsePlace } from "./parse";
+export type { AddressParts, AddressResult, AddressConfig } from "./types";
+export { EMPTY_PARTS } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// @ikeboy003/address — headless Google Places address autocomplete.
+//
+// Core entry (framework-agnostic): the script loader, the place parser, and
+// import-time config. The React binding (`useAddressAutocomplete`, `<AddressAutocomplete>`)
+// lives in `@ikeboy003/address/react`.
+//
+//   import { configureAddress } from "@ikeboy003/address";     // optional
+//   import { useAddressAutocomplete } from "@ikeboy003/address/react";
+//
+// One PUBLIC, referrer-restricted browser key serves every site — restrict it to
+// your domains in the Google console. No backend, no cache: the JS widget is
+// session-billed in the browser and Google's ToS forbids storing predictions.
+export { configureAddress, loadPlaces, addressCountry } from "./loader";
+export { parsePlace } from "./parse";
+export { EMPTY_PARTS } from "./types";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,4EAA4E;AAC5E,4FAA4F;AAC5F,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,iFAAiF;AACjF,6EAA6E;AAC7E,8EAA8E;AAE9E,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,11 @@
+import type { AddressConfig } from "./types";
+/** Override config at import time. Unset fields keep their defaults / env fallback. */
+export declare function configureAddress(next: AddressConfig): void;
+export declare function addressCountry(): string | string[] | null;
+/**
+ * Load `google.maps.places` once. Resolves with `google.maps`. Rejects if no key
+ * is configured or the script fails. Safe to call repeatedly — one script, one
+ * promise. Pass `apiKey` to override the configured/env key for this page.
+ */
+export declare function loadPlaces(apiKey?: string): Promise<typeof google.maps>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAM1D;AAYD,wBAAgB,cAAc,IAAI,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAEzD;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAmCvE"}

package/dist/loader.js

@@ -0,0 +1,77 @@
+// Framework-agnostic loader for the Google Maps JS API (places library). Loads the
+// script exactly once per page and de-dupes concurrent callers behind one promise —
+// three checkout forms mounting at once still yield a single <script>. Browser-only;
+// on the server `load()` returns a never-resolving promise (guarded by callers).
+let config = {
+    apiKey: "",
+    country: "us",
+    version: "weekly",
+};
+/** Override config at import time. Unset fields keep their defaults / env fallback. */
+export function configureAddress(next) {
+    config = {
+        apiKey: next.apiKey ?? config.apiKey,
+        country: next.country === undefined ? config.country : next.country,
+        version: next.version ?? config.version,
+    };
+}
+function resolvedKey(override) {
+    if (override)
+        return override;
+    if (config.apiKey)
+        return config.apiKey;
+    // Env fallback. MUST be the static `process.env.NEXT_PUBLIC_*` member expression —
+    // Next/Vite DefinePlugin replaces exactly this token with the string literal at
+    // build (a dynamic `env[key]` access is NOT inlined and resolves to "" in the
+    // browser). No `typeof process` guard: after inlining, no `process` ref remains.
+    return process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY ?? "";
+}
+export function addressCountry() {
+    return config.country ?? null;
+}
+let loadPromise = null;
+/**
+ * Load `google.maps.places` once. Resolves with `google.maps`. Rejects if no key
+ * is configured or the script fails. Safe to call repeatedly — one script, one
+ * promise. Pass `apiKey` to override the configured/env key for this page.
+ */
+export function loadPlaces(apiKey) {
+    if (loadPromise)
+        return loadPromise;
+    loadPromise = new Promise((resolve, reject) => {
+        if (typeof window === "undefined" || typeof document === "undefined") {
+            // SSR — never resolves; the React hook only calls this in an effect.
+            return;
+        }
+        // Already present (e.g. another lib loaded it).
+        const existing = window.google;
+        if (existing?.maps?.places) {
+            resolve(existing.maps);
+            return;
+        }
+        const key = resolvedKey(apiKey);
+        if (!key) {
+            reject(new Error("@ikeboy003/address: no Maps API key (set NEXT_PUBLIC_GOOGLE_MAPS_API_KEY or configureAddress({ apiKey }))"));
+            loadPromise = null;
+            return;
+        }
+        const params = new URLSearchParams({ key, libraries: "places", v: config.version });
+        const script = document.createElement("script");
+        script.src = `https://maps.googleapis.com/maps/api/js?${params.toString()}`;
+        script.async = true;
+        script.onload = () => {
+            const g = window.google;
+            if (g?.maps?.places)
+                resolve(g.maps);
+            else
+                reject(new Error("@ikeboy003/address: Maps JS loaded but places library missing"));
+        };
+        script.onerror = () => {
+            loadPromise = null;
+            reject(new Error("@ikeboy003/address: failed to load Google Maps JS"));
+        };
+        document.head.appendChild(script);
+    });
+    return loadPromise;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}

package/dist/parse.d.ts

@@ -0,0 +1,8 @@
+import type { AddressResult } from "./types";
+/**
+ * Parse a selected place into `{ formatted, parts, placeId }`. Requires the place
+ * to have been fetched with `fields` including `address_components`,
+ * `formatted_address`, and `place_id` (the hook requests these).
+ */
+export declare function parsePlace(place: google.maps.places.PlaceResult): AddressResult;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAC;AAY3D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,aAAa,CAyB/E"}

package/dist/parse.js

@@ -0,0 +1,40 @@
+// Turn a Google PlaceResult into our structured AddressResult. This is the real
+// value over a raw autocomplete: the site gets ShipTo-shaped fields, not just a
+// display string, so the checkout form auto-fills street/city/state/zip.
+import { EMPTY_PARTS } from "./types";
+/** First component whose `types` include one of `wanted`. */
+function pick(components, wanted, short = false) {
+    const c = components.find((comp) => comp.types.some((t) => wanted.includes(t)));
+    if (!c)
+        return "";
+    return short ? c.short_name : c.long_name;
+}
+/**
+ * Parse a selected place into `{ formatted, parts, placeId }`. Requires the place
+ * to have been fetched with `fields` including `address_components`,
+ * `formatted_address`, and `place_id` (the hook requests these).
+ */
+export function parsePlace(place) {
+    const components = place.address_components ?? [];
+    const streetNumber = pick(components, ["street_number"]);
+    const route = pick(components, ["route"]);
+    const parts = {
+        ...EMPTY_PARTS,
+        street1: [streetNumber, route].filter(Boolean).join(" "),
+        street2: pick(components, ["subpremise"]),
+        // locality is the usual city; fall back to postal_town (UK) / sublocality (some
+        // metros put the city there).
+        city: pick(components, ["locality"]) ||
+            pick(components, ["postal_town"]) ||
+            pick(components, ["sublocality", "sublocality_level_1"]),
+        state: pick(components, ["administrative_area_level_1"], true),
+        postal: pick(components, ["postal_code"]),
+        country: pick(components, ["country"], true) || "US",
+    };
+    return {
+        formatted: place.formatted_address ?? "",
+        parts,
+        placeId: place.place_id ?? "",
+    };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gFAAgF;AAChF,yEAAyE;AAGzE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAItC,6DAA6D;AAC7D,SAAS,IAAI,CAAC,UAAuB,EAAE,MAAgB,EAAE,KAAK,GAAG,KAAK;IACpE,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAClB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAqC;IAC9D,MAAM,UAAU,GAAG,KAAK,CAAC,kBAAkB,IAAI,EAAE,CAAC;IAElD,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAiB;QAC1B,GAAG,WAAW;QACd,OAAO,EAAE,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QACxD,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,YAAY,CAAC,CAAC;QACzC,gFAAgF;QAChF,8BAA8B;QAC9B,IAAI,EACF,IAAI,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,CAAC;YAC9B,IAAI,CAAC,UAAU,EAAE,CAAC,aAAa,CAAC,CAAC;YACjC,IAAI,CAAC,UAAU,EAAE,CAAC,aAAa,EAAE,qBAAqB,CAAC,CAAC;QAC1D,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,6BAA6B,CAAC,EAAE,IAAI,CAAC;QAC9D,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,aAAa,CAAC,CAAC;QACzC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,IAAI,IAAI;KACrD,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,iBAAiB,IAAI,EAAE;QACxC,KAAK;QACL,OAAO,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,45 @@
+import { type InputHTMLAttributes, type RefObject } from "react";
+import type { AddressResult } from "./types";
+export interface UseAddressAutocompleteInput {
+    /** Called with the parsed address when the user picks a prediction. */
+    onSelect: (result: AddressResult) => void;
+    /**
+     * Country restriction. Defaults to the configured value (`"us"`). `null` = no
+     * restriction. Passed to Google's `componentRestrictions`.
+     */
+    country?: string | string[] | null;
+    /** Override the configured/env Maps key for this input. */
+    apiKey?: string;
+    /** Gate attaching (e.g. only when the ship-to form is shown). Default true. */
+    enabled?: boolean;
+}
+export interface UseAddressAutocomplete {
+    /** Attach to your text <input>. */
+    inputRef: RefObject<HTMLInputElement | null>;
+    /** True once the Maps script + widget are attached. */
+    ready: boolean;
+    /** Load/attach error (missing key, script blocked), else null. */
+    error: string | null;
+}
+/**
+ * Headless Places Autocomplete. You render the <input> and style it however you
+ * want; this wires Google to it and calls `onSelect` with parsed fields. Also
+ * swallows the Enter keypress while a prediction list is open so picking a
+ * suggestion never accidentally submits the surrounding form.
+ */
+export declare function useAddressAutocomplete({ onSelect, country, apiKey, enabled, }: UseAddressAutocompleteInput): UseAddressAutocomplete;
+export interface AddressAutocompleteProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onSelect"> {
+    /** Parsed address on selection — spread `result.parts` onto your ShipTo. */
+    onSelect: (result: AddressResult) => void;
+    /** Raw text on every keystroke (before/without a selection). */
+    onRawChange?: (value: string) => void;
+    country?: string | string[] | null;
+    apiKey?: string;
+}
+/**
+ * Minimal styled-by-you input with Places attached. Pass `className` + any input
+ * props; `onSelect` fires on a picked prediction, `onRawChange` on typing. For full
+ * control (labels, error slots, a controlled value) use `useAddressAutocomplete`.
+ */
+export declare function AddressAutocomplete({ onSelect, onRawChange, country, apiKey, ...inputProps }: AddressAutocompleteProps): import("react").JSX.Element;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAMA,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,2BAA2B;IAC1C,uEAAuE;IACvE,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,QAAQ,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC7C,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,OAAO,EACP,MAAM,EACN,OAAc,GACf,EAAE,2BAA2B,GAAG,sBAAsB,CA2DtD;AAID,MAAM,WAAW,wBACf,SAAQ,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAC;IAC/D,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,gEAAgE;IAChE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,WAAW,EACX,OAAO,EACP,MAAM,EACN,GAAG,UAAU,EACd,EAAE,wBAAwB,+BAc1B"}

package/dist/react.js

@@ -0,0 +1,87 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// React binding: a headless hook (you own the <input>) and a thin component. The
+// hook attaches Google's Places Autocomplete to your input, and on selection hands
+// back a parsed AddressResult — the site spreads `result.parts` onto its ShipTo.
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { loadPlaces, addressCountry } from "./loader";
+import { parsePlace } from "./parse";
+/**
+ * Headless Places Autocomplete. You render the <input> and style it however you
+ * want; this wires Google to it and calls `onSelect` with parsed fields. Also
+ * swallows the Enter keypress while a prediction list is open so picking a
+ * suggestion never accidentally submits the surrounding form.
+ */
+export function useAddressAutocomplete({ onSelect, country, apiKey, enabled = true, }) {
+    const inputRef = useRef(null);
+    const acRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    // Keep the latest onSelect without re-attaching the widget every render.
+    const onSelectRef = useRef(onSelect);
+    onSelectRef.current = onSelect;
+    const handlePlace = useCallback(() => {
+        const place = acRef.current?.getPlace();
+        if (place?.address_components)
+            onSelectRef.current(parsePlace(place));
+    }, []);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let cancelled = false;
+        const input = inputRef.current;
+        if (!input)
+            return;
+        // Enter-while-open should pick the suggestion, not submit the form.
+        const onKeyDown = (e) => {
+            if (e.key !== "Enter")
+                return;
+            const pac = document.querySelector(".pac-container");
+            const open = pac instanceof HTMLElement && pac.style.display !== "none" && pac.offsetHeight > 0;
+            if (open)
+                e.preventDefault();
+        };
+        input.addEventListener("keydown", onKeyDown);
+        loadPlaces(apiKey)
+            .then((maps) => {
+            if (cancelled || !inputRef.current || acRef.current)
+                return;
+            const restrict = country === undefined ? addressCountry() : country;
+            const ac = new maps.places.Autocomplete(inputRef.current, {
+                fields: ["address_components", "formatted_address", "place_id"],
+                types: ["address"],
+                ...(restrict ? { componentRestrictions: { country: restrict } } : {}),
+            });
+            ac.addListener("place_changed", handlePlace);
+            acRef.current = ac;
+            setReady(true);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "address autocomplete failed");
+        });
+        return () => {
+            cancelled = true;
+            input.removeEventListener("keydown", onKeyDown);
+            if (acRef.current) {
+                google.maps.event.clearInstanceListeners(acRef.current);
+                acRef.current = null;
+            }
+            setReady(false);
+        };
+    }, [enabled, apiKey, country, handlePlace]);
+    return { inputRef, ready, error };
+}
+/**
+ * Minimal styled-by-you input with Places attached. Pass `className` + any input
+ * props; `onSelect` fires on a picked prediction, `onRawChange` on typing. For full
+ * control (labels, error slots, a controlled value) use `useAddressAutocomplete`.
+ */
+export function AddressAutocomplete({ onSelect, onRawChange, country, apiKey, ...inputProps }) {
+    const { inputRef } = useAddressAutocomplete({ onSelect, country, apiKey });
+    return (_jsx("input", { ref: inputRef, type: "text", autoComplete: "off", ...inputProps, onChange: (e) => {
+            onRawChange?.(e.target.value);
+            inputProps.onChange?.(e);
+        } }));
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/** Structured, US-postal-shaped address fields parsed from a Google place. */
+export interface AddressParts {
+    /** street_number + route, e.g. "1810 N 4th St". */
+    street1: string;
+    /** subpremise (apt/suite/unit), e.g. "Apt 4". Empty if none. */
+    street2: string;
+    /** locality / postal_town / sublocality. */
+    city: string;
+    /** administrative_area_level_1 short code, e.g. "OH". */
+    state: string;
+    /** postal_code. */
+    postal: string;
+    /** ISO-3166 alpha-2 short code, e.g. "US". */
+    country: string;
+}
+/** A selected address: the human string, the parsed parts, and the stable id. */
+export interface AddressResult {
+    /** Google's formatted_address (display string). */
+    formatted: string;
+    /** Parsed fields — spread onto a ShipTo. */
+    parts: AddressParts;
+    /** place_id — the ONLY Google field allowed to be cached/stored long-term. */
+    placeId: string;
+}
+/** Import-time config. Anything unset falls back to env at first use. */
+export interface AddressConfig {
+    /**
+     * Browser Maps JS key. Defaults to `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`. This is a
+     * PUBLIC, referrer-restricted key (it ships in client JS) — restrict it to your
+     * domains in the Google Cloud console, not by secrecy.
+     */
+    apiKey?: string;
+    /**
+     * Country restriction for predictions. Default `"us"`. Pass an array for several,
+     * or `null` to allow all.
+     */
+    country?: string | string[] | null;
+    /** Maps JS API version. Default `"weekly"`. */
+    version?: string;
+}
+export declare const EMPTY_PARTS: AddressParts;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAIA,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,YAAY,CAAC;IACpB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,WAAW,EAAE,YAOzB,CAAC"}

package/dist/types.js

@@ -0,0 +1,12 @@
+// Public shapes. `AddressParts` is deliberately the subset of a checkout `ShipTo`
+// that Google can fill — so a site does `setShip(s => ({ ...s, ...result.parts }))`
+// and the street/city/state/zip land with no field-by-field mapping.
+export const EMPTY_PARTS = {
+    street1: "",
+    street2: "",
+    city: "",
+    state: "",
+    postal: "",
+    country: "US",
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,oFAAoF;AACpF,qEAAqE;AA6CrE,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,IAAI;CACd,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ikeboy003/address",
+  "version": "0.1.1",
+  "description": "Headless Google Places address autocomplete: configure-at-import from env, framework-agnostic loader + parser, optional React hook/component. Returns the formatted string AND structured parts (street1/city/state/postal/country) that drop straight onto a checkout ShipTo. No brand/UI baked in.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "keywords": [
+    "address",
+    "autocomplete",
+    "google-places",
+    "checkout",
+    "shipping",
+    "headless"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/google.maps": "^3.58.1",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ikeboy003/ikeboy-npm-packages.git",
+    "directory": "packages/address"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// @ikeboy003/address — headless Google Places address autocomplete.
+//
+// Core entry (framework-agnostic): the script loader, the place parser, and
+// import-time config. The React binding (`useAddressAutocomplete`, `<AddressAutocomplete>`)
+// lives in `@ikeboy003/address/react`.
+//
+//   import { configureAddress } from "@ikeboy003/address";     // optional
+//   import { useAddressAutocomplete } from "@ikeboy003/address/react";
+//
+// One PUBLIC, referrer-restricted browser key serves every site — restrict it to
+// your domains in the Google console. No backend, no cache: the JS widget is
+// session-billed in the browser and Google's ToS forbids storing predictions.
+
+export { configureAddress, loadPlaces, addressCountry } from "./loader";
+export { parsePlace } from "./parse";
+export type { AddressParts, AddressResult, AddressConfig } from "./types";
+export { EMPTY_PARTS } from "./types";

package/src/loader.ts

@@ -0,0 +1,79 @@
+// Framework-agnostic loader for the Google Maps JS API (places library). Loads the
+// script exactly once per page and de-dupes concurrent callers behind one promise —
+// three checkout forms mounting at once still yield a single <script>. Browser-only;
+// on the server `load()` returns a never-resolving promise (guarded by callers).
+
+import type { AddressConfig } from "./types";
+
+let config: Required<Omit<AddressConfig, "apiKey">> & { apiKey: string } = {
+  apiKey: "",
+  country: "us",
+  version: "weekly",
+};
+
+/** Override config at import time. Unset fields keep their defaults / env fallback. */
+export function configureAddress(next: AddressConfig): void {
+  config = {
+    apiKey: next.apiKey ?? config.apiKey,
+    country: next.country === undefined ? config.country : (next.country as string | string[]),
+    version: next.version ?? config.version,
+  };
+}
+
+function resolvedKey(override?: string): string {
+  if (override) return override;
+  if (config.apiKey) return config.apiKey;
+  // Env fallback. MUST be the static `process.env.NEXT_PUBLIC_*` member expression —
+  // Next/Vite DefinePlugin replaces exactly this token with the string literal at
+  // build (a dynamic `env[key]` access is NOT inlined and resolves to "" in the
+  // browser). No `typeof process` guard: after inlining, no `process` ref remains.
+  return process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY ?? "";
+}
+
+export function addressCountry(): string | string[] | null {
+  return config.country ?? null;
+}
+
+let loadPromise: Promise<typeof google.maps> | null = null;
+
+/**
+ * Load `google.maps.places` once. Resolves with `google.maps`. Rejects if no key
+ * is configured or the script fails. Safe to call repeatedly — one script, one
+ * promise. Pass `apiKey` to override the configured/env key for this page.
+ */
+export function loadPlaces(apiKey?: string): Promise<typeof google.maps> {
+  if (loadPromise) return loadPromise;
+  loadPromise = new Promise((resolve, reject) => {
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      // SSR — never resolves; the React hook only calls this in an effect.
+      return;
+    }
+    // Already present (e.g. another lib loaded it).
+    const existing = (window as unknown as { google?: { maps?: typeof google.maps } }).google;
+    if (existing?.maps?.places) {
+      resolve(existing.maps);
+      return;
+    }
+    const key = resolvedKey(apiKey);
+    if (!key) {
+      reject(new Error("@ikeboy003/address: no Maps API key (set NEXT_PUBLIC_GOOGLE_MAPS_API_KEY or configureAddress({ apiKey }))"));
+      loadPromise = null;
+      return;
+    }
+    const params = new URLSearchParams({ key, libraries: "places", v: config.version });
+    const script = document.createElement("script");
+    script.src = `https://maps.googleapis.com/maps/api/js?${params.toString()}`;
+    script.async = true;
+    script.onload = () => {
+      const g = (window as unknown as { google?: { maps?: typeof google.maps } }).google;
+      if (g?.maps?.places) resolve(g.maps);
+      else reject(new Error("@ikeboy003/address: Maps JS loaded but places library missing"));
+    };
+    script.onerror = () => {
+      loadPromise = null;
+      reject(new Error("@ikeboy003/address: failed to load Google Maps JS"));
+    };
+    document.head.appendChild(script);
+  });
+  return loadPromise;
+}

package/src/parse.ts

@@ -0,0 +1,47 @@
+// Turn a Google PlaceResult into our structured AddressResult. This is the real
+// value over a raw autocomplete: the site gets ShipTo-shaped fields, not just a
+// display string, so the checkout form auto-fills street/city/state/zip.
+
+import type { AddressResult, AddressParts } from "./types";
+import { EMPTY_PARTS } from "./types";
+
+type Component = google.maps.GeocoderAddressComponent;
+
+/** First component whose `types` include one of `wanted`. */
+function pick(components: Component[], wanted: string[], short = false): string {
+  const c = components.find((comp) => comp.types.some((t) => wanted.includes(t)));
+  if (!c) return "";
+  return short ? c.short_name : c.long_name;
+}
+
+/**
+ * Parse a selected place into `{ formatted, parts, placeId }`. Requires the place
+ * to have been fetched with `fields` including `address_components`,
+ * `formatted_address`, and `place_id` (the hook requests these).
+ */
+export function parsePlace(place: google.maps.places.PlaceResult): AddressResult {
+  const components = place.address_components ?? [];
+
+  const streetNumber = pick(components, ["street_number"]);
+  const route = pick(components, ["route"]);
+  const parts: AddressParts = {
+    ...EMPTY_PARTS,
+    street1: [streetNumber, route].filter(Boolean).join(" "),
+    street2: pick(components, ["subpremise"]),
+    // locality is the usual city; fall back to postal_town (UK) / sublocality (some
+    // metros put the city there).
+    city:
+      pick(components, ["locality"]) ||
+      pick(components, ["postal_town"]) ||
+      pick(components, ["sublocality", "sublocality_level_1"]),
+    state: pick(components, ["administrative_area_level_1"], true),
+    postal: pick(components, ["postal_code"]),
+    country: pick(components, ["country"], true) || "US",
+  };
+
+  return {
+    formatted: place.formatted_address ?? "",
+    parts,
+    placeId: place.place_id ?? "",
+  };
+}

package/src/react.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+// React binding: a headless hook (you own the <input>) and a thin component. The
+// hook attaches Google's Places Autocomplete to your input, and on selection hands
+// back a parsed AddressResult — the site spreads `result.parts` onto its ShipTo.
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type InputHTMLAttributes,
+  type RefObject,
+} from "react";
+import { loadPlaces, addressCountry } from "./loader";
+import { parsePlace } from "./parse";
+import type { AddressResult } from "./types";
+
+export interface UseAddressAutocompleteInput {
+  /** Called with the parsed address when the user picks a prediction. */
+  onSelect: (result: AddressResult) => void;
+  /**
+   * Country restriction. Defaults to the configured value (`"us"`). `null` = no
+   * restriction. Passed to Google's `componentRestrictions`.
+   */
+  country?: string | string[] | null;
+  /** Override the configured/env Maps key for this input. */
+  apiKey?: string;
+  /** Gate attaching (e.g. only when the ship-to form is shown). Default true. */
+  enabled?: boolean;
+}
+
+export interface UseAddressAutocomplete {
+  /** Attach to your text <input>. */
+  inputRef: RefObject<HTMLInputElement | null>;
+  /** True once the Maps script + widget are attached. */
+  ready: boolean;
+  /** Load/attach error (missing key, script blocked), else null. */
+  error: string | null;
+}
+
+/**
+ * Headless Places Autocomplete. You render the <input> and style it however you
+ * want; this wires Google to it and calls `onSelect` with parsed fields. Also
+ * swallows the Enter keypress while a prediction list is open so picking a
+ * suggestion never accidentally submits the surrounding form.
+ */
+export function useAddressAutocomplete({
+  onSelect,
+  country,
+  apiKey,
+  enabled = true,
+}: UseAddressAutocompleteInput): UseAddressAutocomplete {
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const acRef = useRef<google.maps.places.Autocomplete | null>(null);
+  const [ready, setReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Keep the latest onSelect without re-attaching the widget every render.
+  const onSelectRef = useRef(onSelect);
+  onSelectRef.current = onSelect;
+
+  const handlePlace = useCallback(() => {
+    const place = acRef.current?.getPlace();
+    if (place?.address_components) onSelectRef.current(parsePlace(place));
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    const input = inputRef.current;
+    if (!input) return;
+
+    // Enter-while-open should pick the suggestion, not submit the form.
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "Enter") return;
+      const pac = document.querySelector(".pac-container");
+      const open = pac instanceof HTMLElement && pac.style.display !== "none" && pac.offsetHeight > 0;
+      if (open) e.preventDefault();
+    };
+    input.addEventListener("keydown", onKeyDown);
+
+    loadPlaces(apiKey)
+      .then((maps) => {
+        if (cancelled || !inputRef.current || acRef.current) return;
+        const restrict = country === undefined ? addressCountry() : country;
+        const ac = new maps.places.Autocomplete(inputRef.current, {
+          fields: ["address_components", "formatted_address", "place_id"],
+          types: ["address"],
+          ...(restrict ? { componentRestrictions: { country: restrict } } : {}),
+        });
+        ac.addListener("place_changed", handlePlace);
+        acRef.current = ac;
+        setReady(true);
+      })
+      .catch((e) => {
+        if (!cancelled) setError(e instanceof Error ? e.message : "address autocomplete failed");
+      });
+
+    return () => {
+      cancelled = true;
+      input.removeEventListener("keydown", onKeyDown);
+      if (acRef.current) {
+        google.maps.event.clearInstanceListeners(acRef.current);
+        acRef.current = null;
+      }
+      setReady(false);
+    };
+  }, [enabled, apiKey, country, handlePlace]);
+
+  return { inputRef, ready, error };
+}
+
+// ── Convenience component ────────────────────────────────────────────────────
+
+export interface AddressAutocompleteProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "onSelect"> {
+  /** Parsed address on selection — spread `result.parts` onto your ShipTo. */
+  onSelect: (result: AddressResult) => void;
+  /** Raw text on every keystroke (before/without a selection). */
+  onRawChange?: (value: string) => void;
+  country?: string | string[] | null;
+  apiKey?: string;
+}
+
+/**
+ * Minimal styled-by-you input with Places attached. Pass `className` + any input
+ * props; `onSelect` fires on a picked prediction, `onRawChange` on typing. For full
+ * control (labels, error slots, a controlled value) use `useAddressAutocomplete`.
+ */
+export function AddressAutocomplete({
+  onSelect,
+  onRawChange,
+  country,
+  apiKey,
+  ...inputProps
+}: AddressAutocompleteProps) {
+  const { inputRef } = useAddressAutocomplete({ onSelect, country, apiKey });
+  return (
+    <input
+      ref={inputRef}
+      type="text"
+      autoComplete="off"
+      {...inputProps}
+      onChange={(e) => {
+        onRawChange?.(e.target.value);
+        inputProps.onChange?.(e);
+      }}
+    />
+  );
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+// Public shapes. `AddressParts` is deliberately the subset of a checkout `ShipTo`
+// that Google can fill — so a site does `setShip(s => ({ ...s, ...result.parts }))`
+// and the street/city/state/zip land with no field-by-field mapping.
+
+/** Structured, US-postal-shaped address fields parsed from a Google place. */
+export interface AddressParts {
+  /** street_number + route, e.g. "1810 N 4th St". */
+  street1: string;
+  /** subpremise (apt/suite/unit), e.g. "Apt 4". Empty if none. */
+  street2: string;
+  /** locality / postal_town / sublocality. */
+  city: string;
+  /** administrative_area_level_1 short code, e.g. "OH". */
+  state: string;
+  /** postal_code. */
+  postal: string;
+  /** ISO-3166 alpha-2 short code, e.g. "US". */
+  country: string;
+}
+
+/** A selected address: the human string, the parsed parts, and the stable id. */
+export interface AddressResult {
+  /** Google's formatted_address (display string). */
+  formatted: string;
+  /** Parsed fields — spread onto a ShipTo. */
+  parts: AddressParts;
+  /** place_id — the ONLY Google field allowed to be cached/stored long-term. */
+  placeId: string;
+}
+
+/** Import-time config. Anything unset falls back to env at first use. */
+export interface AddressConfig {
+  /**
+   * Browser Maps JS key. Defaults to `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`. This is a
+   * PUBLIC, referrer-restricted key (it ships in client JS) — restrict it to your
+   * domains in the Google Cloud console, not by secrecy.
+   */
+  apiKey?: string;
+  /**
+   * Country restriction for predictions. Default `"us"`. Pass an array for several,
+   * or `null` to allow all.
+   */
+  country?: string | string[] | null;
+  /** Maps JS API version. Default `"weekly"`. */
+  version?: string;
+}
+
+export const EMPTY_PARTS: AddressParts = {
+  street1: "",
+  street2: "",
+  city: "",
+  state: "",
+  postal: "",
+  country: "US",
+};