@ticketmaster/tm-global-address 0.7.0 → 0.8.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Phase 7: Form State & Hooks
+ *
+ * Exports:
+ *  - useAddressForm:    Standalone form state hook (no external dependencies)
+ *  - useAddressFormRHF: react-hook-form adapter (same interface, different engine)
+ */
+export { useAddressForm } from './useAddressForm';
+export type { UseAddressFormConfig, UseAddressFormReturn, AddressFormValues, } from './useAddressForm';
+export { useAddressFormRHF } from './useAddressFormRHF';

package/dist/hooks/useAddressForm.d.ts

@@ -0,0 +1,76 @@
+import { SaveAddressPayload, FieldError } from '../types/AddressData';
+import { CountryValidationConfig } from '../types/CountryConfig';
+import { ValidationError, FormValidationResult } from '../validation/types';
+/** Configuration for the useAddressForm hook */
+export interface UseAddressFormConfig {
+    /** Initial values to pre-populate the form (e.g. when editing an existing address) */
+    initialValues?: Partial<SaveAddressPayload>;
+    /** Country validation config. If omitted, derived from initialValues.country or defaults to empty US-fallback. */
+    countryConfig?: CountryValidationConfig;
+    /** Show phone number field */
+    showPhoneNumber?: boolean;
+    /** Called on successful form submission with the validated payload */
+    onSubmit?: (values: SaveAddressPayload) => void;
+    /** Called whenever a field value changes */
+    onChange?: (field: string, value: string | boolean) => void;
+    /** Called whenever validation runs (onBlur or onSubmit) */
+    onValidate?: (errors: ValidationError[]) => void;
+    /** Called when the country field changes (before state reset) */
+    onCountryChange?: (country: string) => void;
+}
+/** Internal form value map — all strings for text fields, boolean for defaultAddress */
+export interface AddressFormValues {
+    firstName: string;
+    lastName: string;
+    country: string;
+    address1: string;
+    address2: string;
+    city: string;
+    postal: string;
+    state: string;
+    phoneNumber: string;
+    defaultAddress: boolean;
+}
+/** The full return value of useAddressForm */
+export interface UseAddressFormReturn {
+    /** Current form values */
+    values: AddressFormValues;
+    /** Field-level validation errors (inline display) */
+    errors: Record<string, ValidationError>;
+    /** Non-field server errors (AlertBox banner display) */
+    nonFieldErrors: ValidationError[];
+    /** Which fields have been touched (focused then blurred) */
+    touched: Record<string, boolean>;
+    /** Whether the form passes full validation */
+    isValid: boolean;
+    /** Whether any field differs from initialValues */
+    isDirty: boolean;
+    /** Update a single field value */
+    setValue: (field: string, value: string | boolean) => void;
+    /** Update multiple field values at once (e.g. pre-populate from API) */
+    setValues: (values: Partial<AddressFormValues>) => void;
+    /** Mark a field as touched and run its blur validation */
+    handleBlur: (field: string) => void;
+    /** Run full form validation and return the result */
+    handleSubmit: () => FormValidationResult;
+    /** Reset form to initial values (or provided values) */
+    reset: (values?: Partial<AddressFormValues>) => void;
+    /** Inject server errors from a failed onSave response */
+    setServerErrors: (errors: FieldError[]) => void;
+}
+/**
+ * useAddressForm — standalone address form state management hook.
+ *
+ * @example
+ * ```tsx
+ * const form = useAddressForm({
+ *   initialValues: { country: 'US' },
+ *   showPhoneNumber: true,
+ *   onChange: (field, value) => console.log(field, value),
+ * });
+ *
+ * // In your form:
+ * <input value={form.values.firstName} onChange={e => form.setValue('firstName', e.target.value)} />
+ * ```
+ */
+export declare function useAddressForm(config?: UseAddressFormConfig): UseAddressFormReturn;

package/dist/hooks/useAddressForm.js

@@ -0,0 +1,174 @@
+import { useRef as Q, useState as F, useCallback as N } from "react";
+import { getCountryConfig as U } from "../data/countryData.js";
+import { FIELD_CONSTRAINTS as g } from "../validation/constants.js";
+import { validateForm as q } from "../validation/validateForm.js";
+import { validatePhoneNumber as B } from "../validation/validatePhoneNumber.js";
+import { validateState as V } from "../validation/validateState.js";
+import { validatePostalCode as z } from "../validation/validatePostalCode.js";
+import { validateTextField as b } from "../validation/validateTextField.js";
+function I(e) {
+  return {
+    firstName: (e == null ? void 0 : e.firstName) ?? "",
+    lastName: (e == null ? void 0 : e.lastName) ?? "",
+    country: (e == null ? void 0 : e.country) ?? "",
+    address1: (e == null ? void 0 : e.address1) ?? "",
+    address2: (e == null ? void 0 : e.address2) ?? "",
+    city: (e == null ? void 0 : e.city) ?? "",
+    postal: (e == null ? void 0 : e.postal) ?? "",
+    state: (e == null ? void 0 : e.state) ?? "",
+    phoneNumber: (e == null ? void 0 : e.phoneNumber) ?? "",
+    defaultAddress: (e == null ? void 0 : e.defaultAddress) ?? !1
+  };
+}
+function G(e, c) {
+  return Object.keys(e).some(
+    (n) => e[n] !== c[n]
+  );
+}
+function H(e, c, n, y) {
+  const s = c[e];
+  switch (e) {
+    case "firstName":
+      return b("firstName", String(s), g.firstName);
+    case "lastName":
+      return b("lastName", String(s), g.lastName);
+    case "address1":
+      return b("address1", String(s), g.address1);
+    case "address2":
+      return !s || String(s) === "" ? null : b("address2", String(s), g.address2);
+    case "city":
+      return b("city", String(s), g.city);
+    case "postal":
+      return !s || String(s) === "" ? null : z(String(s), g.postal, n);
+    case "state":
+      return V(s ? String(s) : void 0, n);
+    case "phoneNumber":
+      return !y || !s || String(s) === "" ? null : B(String(s), n);
+    case "country":
+      return !s || String(s) === "" ? {
+        field: "country",
+        code: "FIELD_REQUIRED",
+        message: "country is required",
+        metadata: { field: "country" }
+      } : null;
+    default:
+      return null;
+  }
+}
+function i(e = {}) {
+  const {
+    initialValues: c,
+    showPhoneNumber: n = !1,
+    onSubmit: y,
+    onChange: s,
+    onValidate: m,
+    onCountryChange: h
+  } = e, A = Q(I(c)), [o, l] = F(
+    () => I(c)
+  ), [S, f] = F({}), [D, O] = F([]), [R, E] = F({}), v = e.countryConfig ?? U(o.country), _ = N(
+    (t, d) => {
+      if (t === "country") {
+        const u = String(d);
+        h == null || h(u), l((r) => ({
+          ...r,
+          country: u,
+          state: ""
+        })), f((r) => {
+          const { country: a, state: p, ...x } = r;
+          return x;
+        });
+      } else
+        l((u) => ({ ...u, [t]: d })), f((u) => {
+          const { [t]: r, ...a } = u;
+          return a;
+        });
+      s == null || s(t, d);
+    },
+    [s, h]
+  ), j = N((t) => {
+    l((d) => ({ ...d, ...t }));
+  }, []), T = N(
+    (t) => {
+      if (E((r) => ({ ...r, [t]: !0 })), typeof o[t] == "boolean") return;
+      const u = H(t, o, v, n);
+      if (f((r) => {
+        if (u) return { ...r, [t]: u };
+        const { [t]: a, ...p } = r;
+        return p;
+      }), m) {
+        const r = u ? { ...S, [t]: u } : Object.fromEntries(Object.entries(S).filter(([a]) => a !== t));
+        m(Object.values(r));
+      }
+    },
+    [o, v, n, S, m]
+  ), C = N(() => {
+    const t = {
+      mode: (c == null ? void 0 : c.mode) ?? "create",
+      ...(c == null ? void 0 : c.mode) === "edit" && (c == null ? void 0 : c.addressId) !== void 0 ? { addressId: c.addressId } : {},
+      defaultAddress: o.defaultAddress,
+      firstName: o.firstName.trim(),
+      lastName: o.lastName.trim(),
+      address1: o.address1.trim(),
+      ...o.address2.trim() ? { address2: o.address2.trim() } : {},
+      city: o.city.trim(),
+      postal: o.postal.trim(),
+      country: o.country,
+      ...o.state ? { state: o.state } : {},
+      ...n && o.phoneNumber ? { phoneNumber: o.phoneNumber.trim() } : {}
+    }, d = q(t, v, { showPhoneNumber: n });
+    if (d.valid)
+      f({}), y == null || y(t);
+    else {
+      const u = {};
+      for (const r of d.errors)
+        u[r.field] = r;
+      f(u), E((r) => {
+        const a = { ...r };
+        for (const p of d.errors)
+          a[p.field] = !0;
+        return a;
+      }), m == null || m(d.errors);
+    }
+    return d;
+  }, [o, v, n, c, y, m]), k = N((t) => {
+    const d = t ? I(t) : { ...A.current };
+    l(d), f({}), O([]), E({});
+  }, []), w = N((t) => {
+    const d = {}, u = [];
+    for (const r of t)
+      r.field && r.field !== "" ? d[r.field] = {
+        field: r.field,
+        code: r.code,
+        message: r.message,
+        metadata: r.metadata
+      } : u.push({
+        field: "",
+        code: r.code || "FIELD_REQUIRED",
+        message: r.message,
+        metadata: r.metadata
+      });
+    f((r) => ({ ...r, ...d })), O(u), E((r) => {
+      const a = { ...r };
+      for (const p of Object.keys(d))
+        a[p] = !0;
+      return a;
+    });
+  }, []), L = Object.keys(S).length === 0 && D.length === 0, P = G(o, A.current);
+  return {
+    values: o,
+    errors: S,
+    nonFieldErrors: D,
+    touched: R,
+    isValid: L,
+    isDirty: P,
+    setValue: _,
+    setValues: j,
+    handleBlur: T,
+    handleSubmit: C,
+    reset: k,
+    setServerErrors: w
+  };
+}
+export {
+  i as useAddressForm
+};

package/dist/hooks/useAddressFormRHF.d.ts

@@ -0,0 +1,8 @@
+import { UseAddressFormConfig, UseAddressFormReturn } from './useAddressForm';
+/**
+ * useAddressFormRHF — react-hook-form-backed address form state hook.
+ *
+ * Produces the same UseAddressFormReturn as useAddressForm so consuming
+ * components are agnostic to which hook is used.
+ */
+export declare function useAddressFormRHF(config?: UseAddressFormConfig): UseAddressFormReturn;

package/dist/hooks/useAddressFormRHF.js

@@ -0,0 +1,174 @@
+import { useCallback as N } from "react";
+import { useForm as Q } from "react-hook-form";
+import { getCountryConfig as C } from "../data/countryData.js";
+import { FIELD_CONSTRAINTS as S } from "../validation/constants.js";
+import { validateForm as U } from "../validation/validateForm.js";
+import { validatePhoneNumber as k } from "../validation/validatePhoneNumber.js";
+import { validateState as x } from "../validation/validateState.js";
+import { validatePostalCode as B } from "../validation/validatePostalCode.js";
+import { validateTextField as l } from "../validation/validateTextField.js";
+function q(f, r, o, u) {
+  const t = r[f];
+  switch (f) {
+    case "firstName":
+      return l("firstName", String(t), S.firstName);
+    case "lastName":
+      return l("lastName", String(t), S.lastName);
+    case "address1":
+      return l("address1", String(t), S.address1);
+    case "address2":
+      return !t || String(t) === "" ? null : l("address2", String(t), S.address2);
+    case "city":
+      return l("city", String(t), S.city);
+    case "postal":
+      return !t || String(t) === "" ? null : B(String(t), S.postal, o);
+    case "state":
+      return x(t ? String(t) : void 0, o);
+    case "phoneNumber":
+      return !u || !t || String(t) === "" ? null : k(String(t), o);
+    case "country":
+      return !t || String(t) === "" ? {
+        field: "country",
+        code: "FIELD_REQUIRED",
+        message: "country is required",
+        metadata: { field: "country" }
+      } : null;
+    default:
+      return null;
+  }
+}
+function Z(f = {}) {
+  const {
+    initialValues: r,
+    showPhoneNumber: o = !1,
+    onSubmit: u,
+    onChange: t,
+    onValidate: c,
+    onCountryChange: h
+  } = f, b = {
+    firstName: (r == null ? void 0 : r.firstName) ?? "",
+    lastName: (r == null ? void 0 : r.lastName) ?? "",
+    country: (r == null ? void 0 : r.country) ?? "",
+    address1: (r == null ? void 0 : r.address1) ?? "",
+    address2: (r == null ? void 0 : r.address2) ?? "",
+    city: (r == null ? void 0 : r.city) ?? "",
+    postal: (r == null ? void 0 : r.postal) ?? "",
+    state: (r == null ? void 0 : r.state) ?? "",
+    phoneNumber: (r == null ? void 0 : r.phoneNumber) ?? "",
+    defaultAddress: (r == null ? void 0 : r.defaultAddress) ?? !1
+  }, {
+    watch: D,
+    setValue: g,
+    setError: y,
+    clearErrors: m,
+    reset: F,
+    formState: p,
+    getValues: i
+  } = Q({
+    defaultValues: b,
+    mode: "onBlur"
+  }), R = D(), v = {};
+  for (const [e, s] of Object.entries(p.errors))
+    s && typeof s.message == "string" && (v[e] = {
+      field: e,
+      code: "FIELD_REQUIRED",
+      // RHF default; overridden by setServerErrors
+      message: s.message
+    });
+  const A = N(
+    (e, s) => {
+      if (e === "country") {
+        const d = String(s);
+        h == null || h(d), g("country", d), g("state", ""), m(["country", "state"]);
+      } else
+        g(e, s), m(e);
+      t == null || t(e, s);
+    },
+    [g, m, t, h]
+  ), O = N(
+    (e) => {
+      for (const [s, d] of Object.entries(e))
+        g(s, d);
+    },
+    [g]
+  ), j = N(
+    (e) => {
+      const s = i(), d = C(s.country), n = q(e, s, d, o);
+      if (n) {
+        y(e, { message: n.message });
+        const E = Object.entries(p.errors).filter(([, a]) => a && typeof a.message == "string").map(([a, P]) => ({
+          field: a,
+          code: "FIELD_REQUIRED",
+          message: P.message
+        }));
+        c == null || c([...E, n]);
+      } else
+        m(e);
+    },
+    [i, o, y, m, p.errors, c]
+  ), L = N(() => {
+    var E;
+    const e = i(), s = f.countryConfig ?? C(e.country), d = {
+      mode: (r == null ? void 0 : r.mode) ?? "create",
+      ...(r == null ? void 0 : r.mode) === "edit" && (r == null ? void 0 : r.addressId) !== void 0 ? { addressId: r.addressId } : {},
+      defaultAddress: e.defaultAddress,
+      firstName: e.firstName.trim(),
+      lastName: e.lastName.trim(),
+      address1: e.address1.trim(),
+      ...(E = e.address2) != null && E.trim() ? { address2: e.address2.trim() } : {},
+      city: e.city.trim(),
+      postal: e.postal.trim(),
+      country: e.country,
+      ...e.state ? { state: e.state } : {},
+      ...o && e.phoneNumber ? { phoneNumber: e.phoneNumber.trim() } : {}
+    }, n = U(d, s, { showPhoneNumber: o });
+    if (n.valid)
+      m(), u == null || u(d);
+    else {
+      for (const a of n.errors)
+        y(a.field, { message: a.message });
+      c == null || c(n.errors);
+    }
+    return n;
+  }, [
+    i,
+    f.countryConfig,
+    o,
+    r,
+    y,
+    m,
+    u,
+    c
+  ]), T = N(
+    (e) => {
+      F(e ? { ...b, ...e } : b);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [F]
+  ), _ = [], w = N(
+    (e) => {
+      for (const s of e)
+        s.field && s.field !== "" && y(s.field, { message: s.message });
+    },
+    [y]
+  ), I = {};
+  for (const [e, s] of Object.entries(p.touchedFields))
+    s && (I[e] = !0);
+  return {
+    values: R,
+    errors: v,
+    nonFieldErrors: _,
+    touched: I,
+    isValid: p.isValid && Object.keys(v).length === 0,
+    isDirty: p.isDirty,
+    setValue: A,
+    setValues: O,
+    handleBlur: j,
+    handleSubmit: L,
+    reset: T,
+    setServerErrors: w
+  };
+}
+export {
+  Z as useAddressFormRHF
+};

package/dist/index.d.ts

@@ -26,5 +26,7 @@ export { sanitize, validateTextField, validatePostalCode, validateState, validat
 export type { ValidateFormOptions } from './validation/index';
 export { useLabels, resolveLabels, loadBundle, isRTLLocale, interpolate, SUPPORTED_LOCALES, } from './i18n/index';
 export type { ResolvedLabels, LocaleBundle, FormLabels, ValidationLabels, CountryOverrides, InterpolationVars, SupportedLocale, } from './i18n/index';
+export { useAddressForm, useAddressFormRHF } from './hooks/index';
+export type { UseAddressFormConfig, UseAddressFormReturn, AddressFormValues } from './hooks/index';
 export { HelloWorld } from './components/HelloWorld/HelloWorld';
 export type { HelloWorldProps } from './components/HelloWorld/HelloWorld';

package/dist/index.js

@@ -1,55 +1,59 @@
 import { GlobalAddress as e } from "./components/GlobalAddress/GlobalAddress.js";
 import { AddressForm as m } from "./components/AddressForm/AddressForm.js";
-import { PhoneField as d } from "./components/PhoneField/PhoneField.js";
-import { AddressCard as s, formatAddressSummary as p } from "./components/AddressCard/AddressCard.js";
+import { PhoneField as s } from "./components/PhoneField/PhoneField.js";
+import { AddressCard as f, formatAddressSummary as p } from "./components/AddressCard/AddressCard.js";
 import { AddressSummary as l } from "./components/AddressSummary/AddressSummary.js";
 import { AddressList as i } from "./components/AddressList/AddressList.js";
-import { COUNTRIES as T, getCountryByCode as O } from "./data/countries.js";
-import { SUBDIVISIONS as A, getSubdivisions as N } from "./data/states.js";
-import { POSTAL_PATTERNS as u, getPostalPattern as E } from "./data/postalPatterns.js";
-import { STATE_REQUIRED_CODES as L } from "./data/countryConfig.js";
-import { COUNTRY_CONFIGS as v, COUNTRY_OPTIONS as _, getCountryConfig as g, getCountryName as y } from "./data/countryData.js";
+import { COUNTRIES as T, getCountryByCode as A } from "./data/countries.js";
+import { SUBDIVISIONS as n, getSubdivisions as u } from "./data/states.js";
+import { POSTAL_PATTERNS as P, getPostalPattern as R } from "./data/postalPatterns.js";
+import { STATE_REQUIRED_CODES as F } from "./data/countryConfig.js";
+import { COUNTRY_CONFIGS as L, COUNTRY_OPTIONS as v, getCountryConfig as _, getCountryName as g } from "./data/countryData.js";
 import { FIELD_CONSTRAINTS as U } from "./validation/constants.js";
 import { SUPPORTED_LOCALES as D, useLabels as B } from "./i18n/index.js";
 import { HelloWorld as G } from "./components/HelloWorld/HelloWorld.js";
-import { interpolate as c, isRTLLocale as z, loadBundle as H, resolveLabels as Q } from "./i18n/labelResolver.js";
+import { interpolate as Y, isRTLLocale as c, loadBundle as z, resolveLabels as Q } from "./i18n/labelResolver.js";
 import { sanitize as W } from "./validation/sanitize.js";
-import { validateForm as k } from "./validation/validateForm.js";
-import { validatePhoneNumber as w } from "./validation/validatePhoneNumber.js";
-import { validatePostalCode as K } from "./validation/validatePostalCode.js";
-import { validateState as X } from "./validation/validateState.js";
-import { validateTextField as $ } from "./validation/validateTextField.js";
+import { useAddressForm as k } from "./hooks/useAddressForm.js";
+import { useAddressFormRHF as w } from "./hooks/useAddressFormRHF.js";
+import { validateForm as K } from "./validation/validateForm.js";
+import { validatePhoneNumber as X } from "./validation/validatePhoneNumber.js";
+import { validatePostalCode as $ } from "./validation/validatePostalCode.js";
+import { validateState as or } from "./validation/validateState.js";
+import { validateTextField as tr } from "./validation/validateTextField.js";
 export {
-  s as AddressCard,
+  f as AddressCard,
   m as AddressForm,
   i as AddressList,
   l as AddressSummary,
   T as COUNTRIES,
-  v as COUNTRY_CONFIGS,
-  _ as COUNTRY_OPTIONS,
+  L as COUNTRY_CONFIGS,
+  v as COUNTRY_OPTIONS,
   U as FIELD_CONSTRAINTS,
   e as GlobalAddress,
   G as HelloWorld,
-  u as POSTAL_PATTERNS,
-  d as PhoneField,
-  L as STATE_REQUIRED_CODES,
-  A as SUBDIVISIONS,
+  P as POSTAL_PATTERNS,
+  s as PhoneField,
+  F as STATE_REQUIRED_CODES,
+  n as SUBDIVISIONS,
   D as SUPPORTED_LOCALES,
   p as formatAddressSummary,
-  O as getCountryByCode,
-  g as getCountryConfig,
-  y as getCountryName,
-  E as getPostalPattern,
-  N as getSubdivisions,
-  c as interpolate,
-  z as isRTLLocale,
-  H as loadBundle,
+  A as getCountryByCode,
+  _ as getCountryConfig,
+  g as getCountryName,
+  R as getPostalPattern,
+  u as getSubdivisions,
+  Y as interpolate,
+  c as isRTLLocale,
+  z as loadBundle,
   Q as resolveLabels,
   W as sanitize,
+  k as useAddressForm,
+  w as useAddressFormRHF,
   B as useLabels,
-  k as validateForm,
-  w as validatePhoneNumber,
-  K as validatePostalCode,
-  X as validateState,
-  $ as validateTextField
+  K as validateForm,
+  X as validatePhoneNumber,
+  $ as validatePostalCode,
+  or as validateState,
+  tr as validateTextField
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticketmaster/tm-global-address",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Shared React UI Library for Global Address Management",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -52,6 +52,7 @@
     "prettier": "3.0.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-hook-form": "^7.72.1",
     "storybook": "^8.2.4",
     "styled-components": "^6.4.0",
     "tsconfig-paths-webpack-plugin": "^4.1.0",