@whop/elements-react-native 0.1.0

package/src/core/address/form-state.ts

@@ -0,0 +1,479 @@
+// ported verbatim from frontend/apps/web/src/elements/address-form/form-state.ts — keep in sync when the web element changes
+
+import type { CountryFormat, EmittedAddress } from './engine';
+/**
+ * The address form's ONE state atom (useReducer shape) + the schema-driven central validator.
+ * Country lives IN the atom; hydration is ONE seed (defaultValues > detected IP country >
+ * currency-country hint > US) computed before first paint; reveal-vs-autofill is reducer
+ * state, not component-local flags. Pure module — the jsdom suites drive it directly.
+ */
+import type { ParsedPlaceAddress } from './places';
+
+import { emitAddress, normalizeCountry, postalCodeMatches } from './engine';
+
+export type AddressValueKey =
+  | 'name'
+  | 'first_name'
+  | 'last_name'
+  | 'organization'
+  | 'line1'
+  | 'line2'
+  | 'city'
+  | 'state'
+  | 'postal_code';
+
+export type AddressValues = Partial<Record<AddressValueKey, string>>;
+
+export interface CustomFieldSpec {
+  key: string;
+  label: string;
+  type: 'text' | 'select' | 'date' | 'phone';
+  position: 'after_name' | 'after_organization' | 'before_country' | 'after_address';
+  required?: boolean;
+  options?: string[];
+  format?: string;
+  autocomplete?: string;
+}
+
+export interface AddressFormConfig {
+  mode: 'billing' | 'shipping';
+  layout: 'compact' | 'full';
+  scope: 'minimal' | 'full';
+  name: 'combined' | 'split' | 'none';
+  organization: 'none' | 'name' | 'name_with_type';
+  line2: 'toggle' | 'always' | 'never';
+  autocomplete: boolean;
+  allowedCountries?: string[];
+  customFields?: CustomFieldSpec[];
+  /** Composed-mode method floor: contract keys the selected payment method additionally
+   *  requires (unioned into the visible + required set). */
+  requiredFloor?: string[];
+}
+
+export interface AddressSeedInput {
+  defaultValues?: { name?: string; address?: Partial<EmittedAddress> };
+  detectedCountry?: string;
+  countryHint?: string;
+}
+
+export interface AddressFormState {
+  country: string;
+  values: AddressValues;
+  organizationType: 'business' | 'individual' | '';
+  custom: Record<string, string>;
+  revealed: boolean;
+  line2Open: boolean;
+  selecting: boolean;
+  touched: Partial<Record<string, boolean>>;
+  showAllErrors: boolean;
+}
+
+export type AddressFormAction =
+  | { type: 'edit'; field: AddressValueKey; value: string; autofilled?: boolean }
+  | { type: 'edit-custom'; key: string; value: string }
+  | { type: 'set-organization-type'; value: 'business' | 'individual' | '' }
+  | { type: 'set-country'; country: string }
+  | { type: 'begin-select' }
+  | { type: 'select-failed' }
+  | { type: 'apply-place'; parsed: ParsedPlaceAddress; allowed: string[] }
+  | { type: 'reveal'; autofill?: boolean }
+  | { type: 'toggle-line2' }
+  | { type: 'blur'; field: string }
+  | { type: 'show-errors' };
+
+export function allowedCountryList(config: AddressFormConfig, catalogCountries: string[]): string[] {
+  const raw = config.allowedCountries ?? [];
+  const allowed = raw.map((code) => normalizeCountry(code)).filter((code): code is string => Boolean(code));
+  // Fail LOUD, never open: a list where every entry failed ISO2 normalization (['USA']) is a
+  // config error — silently widening to the whole catalog would undo the merchant's restriction
+  // on a typo. Same refusal bar as the charge config's plan-XOR gate.
+  if (raw.length > 0 && allowed.length === 0) {
+    throw new Error(
+      `allowedCountries has no valid ISO2 entries (got ${JSON.stringify(raw)}) — use two-letter codes like 'US'`,
+    );
+  }
+  return allowed.length > 0 ? allowed : catalogCountries;
+}
+
+function clampCountry(candidate: string | undefined, allowed: string[]): string | undefined {
+  return candidate && allowed.includes(candidate) ? candidate : undefined;
+}
+
+export function seedAddressForm(
+  config: AddressFormConfig,
+  seed: AddressSeedInput,
+  catalogCountries: string[],
+): AddressFormState {
+  const allowed = allowedCountryList(config, catalogCountries);
+  const country =
+    clampCountry(normalizeCountry(seed.defaultValues?.address?.country), allowed) ??
+    clampCountry(normalizeCountry(seed.detectedCountry), allowed) ??
+    clampCountry(normalizeCountry(seed.countryHint), allowed) ??
+    clampCountry('US', allowed) ??
+    allowed.at(0) ??
+    'US';
+  const preset = seed.defaultValues?.address ?? {};
+  const values: AddressValues = {};
+  const putSeed = (key: AddressValueKey, value: string | undefined) => {
+    if (value?.trim()) values[key] = value;
+  };
+  putSeed('name', seed.defaultValues?.name ?? preset.name);
+  putSeed('first_name', preset.first_name);
+  putSeed('last_name', preset.last_name);
+  putSeed('organization', preset.organization);
+  putSeed('line1', preset.line1);
+  putSeed('line2', preset.line2);
+  putSeed('city', preset.city);
+  putSeed('state', preset.state);
+  putSeed('postal_code', preset.postal_code);
+  const seededBeyondLine1 = Boolean(values.city || values.state || values.postal_code || values.line2);
+  return {
+    country,
+    values,
+    organizationType: preset.organization_type ?? '',
+    custom: {},
+    revealed: config.scope === 'minimal' || seededBeyondLine1,
+    line2Open: config.line2 === 'always' || Boolean(values.line2),
+    selecting: false,
+    touched: {},
+    showAllErrors: false,
+  };
+}
+
+const GRID_FIELDS: ReadonlySet<AddressValueKey> = new Set(['city', 'state', 'postal_code', 'line2']);
+
+export function addressFormReducer(state: AddressFormState, action: AddressFormAction): AddressFormState {
+  switch (action.type) {
+    case 'edit': {
+      const values = { ...state.values, [action.field]: action.value };
+      // Two autofill-reveal rails: a value landing in a still-hidden grid field (Chrome fills
+      // hidden SELECTS despite skipping hidden inputs), and an `autofilled` edit — an
+      // inputType-less/insertReplacementText input event on a visible field, the shape every
+      // engine's fill produces and typing never does.
+      const landedHidden = !state.revealed && GRID_FIELDS.has(action.field) && action.value.trim().length > 0;
+      const autofillReveal = Boolean(action.autofilled) && action.value.trim().length > 0;
+      // An autofill commit also opens line2 in toggle mode, in the SAME state commit that
+      // reveals the grid: a conditionally-rendered line2 has no control for Chrome's refill
+      // pass to land in, so an autofilled line2 value would be silently dropped. Once open it
+      // stays open — re-collapsing on an empty settle would be another control-list mutation.
+      const autofillCommit = landedHidden || autofillReveal;
+      return {
+        ...state,
+        values,
+        revealed: state.revealed || autofillCommit,
+        line2Open: state.line2Open || autofillCommit || (action.field === 'line2' && action.value.trim().length > 0),
+        // ANY value activity cancels a pending pick — a fill landing on another cell (autofill
+        // probe, refill pass) mid-resolve invalidates the resolve at the line1 cell, and a
+        // stranded `selecting` would block the suggestions popover until the next line1 edit.
+        selecting: false,
+      };
+    }
+    case 'edit-custom':
+      return { ...state, custom: { ...state.custom, [action.key]: action.value } };
+    case 'set-organization-type':
+      return { ...state, organizationType: action.value };
+    case 'set-country': {
+      const country = normalizeCountry(action.country);
+      if (!country || country === state.country) return state;
+      // A country switch keeps line1/line2/city but drops the state selection (subdivision
+      // keys are country-scoped) — postal stays and revalidates under the new zipRegex. It also
+      // cancels an in-flight place selection: the buyer's country choice supersedes the pick
+      // (the line1 cell drops the resolve on the distribution clock).
+      return { ...state, country, values: { ...state.values, state: undefined }, selecting: false };
+    }
+    case 'begin-select':
+      return { ...state, selecting: true };
+    case 'select-failed':
+      return { ...state, selecting: false };
+    case 'apply-place': {
+      const { parsed, allowed } = action;
+      if (!placeAllowed(allowed, parsed)) return { ...state, selecting: false };
+      // Locality grid = WHOLE-REPLACE on purpose: a chosen place is one address, and mixing a
+      // prior postal/city with the new street is a franken-address AVS hazard (a place-omitted
+      // cell stays empty and focus-first-empty lands there). line1 keeps the typed entry only
+      // when the parse has no street line; line2 (subpremise) is place-data almost never, so
+      // the user's unit number survives the pick.
+      const values: AddressValues = {
+        ...state.values,
+        line1: parsed.line1 ?? state.values.line1,
+        line2: parsed.line2 ?? state.values.line2,
+        city: parsed.city ?? '',
+        state: parsed.state ?? '',
+        postal_code: parsed.postal_code ?? '',
+      };
+      return {
+        ...state,
+        country: parsed.country ?? state.country,
+        values,
+        revealed: true,
+        line2Open: state.line2Open || Boolean(parsed.line2),
+        selecting: false,
+      };
+    }
+    case 'reveal': {
+      const line2Open = state.line2Open || Boolean(action.autofill);
+      if (state.revealed && line2Open === state.line2Open) return state;
+      return { ...state, revealed: true, line2Open };
+    }
+    case 'toggle-line2':
+      return { ...state, line2Open: !state.line2Open };
+    case 'blur': {
+      const touched = { ...state.touched, [action.field]: true };
+      const revealOnLine1 = action.field === 'line1' && Boolean(state.values.line1?.trim());
+      return { ...state, touched, revealed: state.revealed || revealOnLine1 };
+    }
+    case 'show-errors':
+      return { ...state, showAllErrors: true };
+    default:
+      return state;
+  }
+}
+
+export type AddressErrorCode = 'required' | 'invalid';
+
+export interface AddressValidation {
+  errors: Partial<Record<string, AddressErrorCode>>;
+  complete: boolean;
+}
+
+export interface FieldPlan {
+  /** Address-grid fields in the country format's order, filtered to the config scope. */
+  gridFields: Array<'line1' | 'city' | 'state' | 'postal_code'>;
+  required: ReadonlySet<string>;
+}
+
+/** The commit-point allow gate ([] = unrestricted): a restrictive list declines a foreign OR
+ *  country-less parse — unknown provenance must not land foreign locality data under the locked
+ *  ISO2. Shared by the reducer arm and the placeSelected reaction (which must know BEFORE
+ *  reducing whether to mark the commit `placed` — a declined pick must not bump placeSeq). */
+/** The Places-gate allow list: [] = unrestricted. DISTINCT from allowedCountryList (the
+ *  country-select options, which falls back to the whole catalog) — feeding that catalog
+ *  fallback into placeAllowed would wrongly decline catalog-missing territories on
+ *  unrestricted configs. */
+/**
+ * The floor a scope implies, which is what makes `scope="minimal"` mean anything.
+ *
+ * Minimal renders EXACTLY the floor, so an empty floor renders an empty grid: the element shipped a
+ * country select and nothing else, and a buyer could complete that form while the card confirm then
+ * refused at the AVS check for a postal code never collected. Web wires the same value at
+ * apps/web/src/elements/payments/address.tsx:317.
+ */
+export function requiredFloorFor(scope: AddressFormConfig['scope']): string[] | undefined {
+  return scope === 'minimal' ? ['postal_code'] : undefined;
+}
+
+export function placeAllowList(config: AddressFormConfig, catalogCountries: string[]): string[] {
+  return config.allowedCountries?.length ? allowedCountryList(config, catalogCountries) : [];
+}
+
+export function placeAllowed(allowed: string[], parsed: ParsedPlaceAddress): boolean {
+  if (allowed.length === 0) return true;
+  return Boolean(parsed.country && allowed.includes(parsed.country));
+}
+
+const CONTRACT_GRID_KEYS = new Set(['line1', 'city', 'state', 'postal_code']);
+
+/** The schema for a (country, config) pair: which grid fields exist and which fields are
+ *  required. Full scope = the country format's fields (its `require` flags) ∪ the floor;
+ *  minimal scope = EXACTLY the floor (plus country, the form's spine). */
+export function planFields(config: AddressFormConfig, format: CountryFormat): FieldPlan {
+  const floor = new Set((config.requiredFloor ?? []).filter((key) => key !== 'country'));
+  const required = new Set<string>(['country']);
+  const gridFields: FieldPlan['gridFields'] = [];
+
+  const formatHas = (type: 'line1' | 'city' | 'state' | 'postal_code') =>
+    format.fields.some((field) => field.type === type);
+  const formatRequires = (type: string) => format.fields.some((field) => field.type === type && field.required);
+
+  // Minimal = EXACTLY the floor (the method-declared payment minimum — no universal
+  // postal/AVS baseline); full = the country format, widened by the floor.
+  const includeGrid = (type: 'line1' | 'city' | 'state' | 'postal_code') => {
+    if (config.scope === 'minimal') return floor.has(type);
+    return formatHas(type) || floor.has(type);
+  };
+
+  const orderedTypes: Array<'line1' | 'city' | 'state' | 'postal_code'> = [];
+  for (const field of format.fields) {
+    if (field.type === 'line1' || field.type === 'city' || field.type === 'state' || field.type === 'postal_code') {
+      orderedTypes.push(field.type);
+    }
+  }
+  for (const key of ['line1', 'city', 'state', 'postal_code'] as const) {
+    if (!orderedTypes.includes(key)) orderedTypes.push(key);
+  }
+  for (const type of orderedTypes) {
+    if (includeGrid(type)) gridFields.push(type);
+  }
+
+  for (const type of gridFields) {
+    if (config.scope === 'minimal') {
+      required.add(type);
+    } else if (formatRequires(type) || floor.has(type)) {
+      required.add(type);
+    }
+  }
+  if (config.scope === 'full' && gridFields.includes('line1')) required.add('line1');
+
+  if (config.name === 'combined') required.add('name');
+  if (config.name === 'split') {
+    required.add('first_name');
+    required.add('last_name');
+  }
+  if (config.name === 'none' && floor.has('name')) required.add('name');
+  if (config.organization !== 'none' && floor.has('organization')) required.add('organization');
+  for (const field of config.customFields ?? []) {
+    if (field.required) required.add(`custom:${field.key}`);
+  }
+  return { gridFields, required };
+}
+
+/** Custom-field values are short by nature (tax ids, VAT numbers) — anything past this bound is
+ *  invalid WITHOUT running the merchant's pattern, which also removes the buyer-controlled half
+ *  of a catastrophic-backtracking blowup (cost scales with tested input length; the pattern
+ *  author is the embedding page's owner, so the residual risk is self-scoped jank). */
+const CUSTOM_FORMAT_INPUT_CAP = 320;
+
+const customFormatCache = new Map<string, RegExp | null>();
+
+function customFieldPattern(format: string): RegExp | null {
+  let compiled = customFormatCache.get(format);
+  if (compiled === undefined) {
+    try {
+      compiled = new RegExp(format);
+    } catch {
+      compiled = null;
+    }
+    customFormatCache.set(format, compiled);
+  }
+  return compiled;
+}
+
+function customFieldMatches(spec: CustomFieldSpec, value: string): boolean {
+  if (!spec.format || !value) return true;
+  if (value.length > CUSTOM_FORMAT_INPUT_CAP) return false;
+  return customFieldPattern(spec.format)?.test(value) ?? true;
+}
+
+export function validateAddressForm(
+  config: AddressFormConfig,
+  format: CountryFormat,
+  state: AddressFormState,
+): AddressValidation {
+  const plan = planFields(config, format);
+  const errors: Partial<Record<string, AddressErrorCode>> = {};
+  const has = (key: AddressValueKey) => Boolean(state.values[key]?.trim());
+
+  for (const key of plan.required) {
+    if (key === 'country') continue;
+    if (key.startsWith('custom:')) {
+      if (!state.custom[key.slice('custom:'.length)]?.trim()) errors[key] = 'required';
+      continue;
+    }
+    if (CONTRACT_GRID_KEYS.has(key) && !plan.gridFields.includes(key as FieldPlan['gridFields'][number])) continue;
+    if (!has(key as AddressValueKey)) errors[key] = 'required';
+  }
+
+  const postal = state.values.postal_code?.trim() ?? '';
+  if (plan.gridFields.includes('postal_code') && postal && !postalCodeMatches(format.zipRegex, postal)) {
+    errors.postal_code = 'invalid';
+  }
+  for (const spec of config.customFields ?? []) {
+    const key = `custom:${spec.key}`;
+    if (errors[key]) continue;
+    const value = state.custom[spec.key]?.trim() ?? '';
+    if (value && !customFieldMatches(spec, value)) errors[key] = 'invalid';
+  }
+  return { errors, complete: Object.keys(errors).length === 0 };
+}
+
+/** Compact = city and postal share ONE row (format order within it), state below. */
+export function pairedGridRows(gridFields: FieldPlan['gridFields']): Array<Array<'city' | 'state' | 'postal_code'>> {
+  const grid = gridFields.filter((key): key is 'city' | 'state' | 'postal_code' => key !== 'line1');
+  const pair = grid.filter((key) => key !== 'state');
+  const rows: Array<Array<'city' | 'state' | 'postal_code'>> = [];
+  if (pair.length > 0) rows.push(pair);
+  if (grid.includes('state')) rows.push(['state']);
+  return rows;
+}
+
+const TOP_CORNERS = { solo: 'rounded-t-[7px]', first: 'rounded-tl-[7px]', last: 'rounded-tr-[7px]' };
+const BOTTOM_CORNERS = { solo: 'rounded-b-[7px]', first: 'rounded-bl-[7px]', last: 'rounded-br-[7px]' };
+
+/** Box-shadows follow the element's OWN border-radius, so the compact group's rounded
+ *  container cannot round the focus/invalid rings its cells paint — first- and last-row cells
+ *  carry their corner radii themselves (7px = the container's 8px radius minus its 1px
+ *  border), each cell of a two-column row rounding only its outer corner. Derived from the
+ *  same config + field plan that orders the rows: country formats drop and reorder fields,
+ *  and until the grid reveals the visible group ends at line1. */
+export function compactCellCorners(
+  config: AddressFormConfig,
+  gridFields: FieldPlan['gridFields'],
+  visible: { line2: boolean; revealed: boolean },
+): Record<string, string> {
+  const customRows = (position: CustomFieldSpec['position']) =>
+    (config.customFields ?? []).filter((field) => field.position === position).map((field) => [`custom:${field.key}`]);
+  const rows: string[][] = [];
+  if (config.name === 'split') rows.push(['first_name', 'last_name']);
+  else if (config.name === 'combined') rows.push(['name']);
+  rows.push(...customRows('after_name'));
+  if (config.organization === 'name_with_type') rows.push(['organization', 'organization_type']);
+  else if (config.organization === 'name') rows.push(['organization']);
+  rows.push(...customRows('after_organization'), ...customRows('before_country'));
+  rows.push(['country']);
+  if (gridFields.includes('line1')) rows.push(['line1']);
+  if (visible.revealed) {
+    if (visible.line2) rows.push(['line2']);
+    rows.push(...pairedGridRows(gridFields), ...customRows('after_address'));
+  }
+  const classes: Record<string, string> = {};
+  const mark = (row: string[] | undefined, corner: typeof TOP_CORNERS) => {
+    row?.forEach((key, index) => {
+      const cls = row.length === 1 ? corner.solo : index === 0 ? corner.first : corner.last;
+      classes[key] = classes[key] ? `${classes[key]} ${cls}` : cls;
+    });
+  };
+  mark(rows[0], TOP_CORNERS);
+  mark(rows[rows.length - 1], BOTTOM_CORNERS);
+  return classes;
+}
+
+export interface AddressSnapshot {
+  complete: boolean;
+  address: EmittedAddress;
+  custom: Record<string, string>;
+  errors: Partial<Record<string, AddressErrorCode>>;
+}
+
+export function snapshotAddressForm(
+  config: AddressFormConfig,
+  format: CountryFormat,
+  state: AddressFormState,
+): AddressSnapshot {
+  const validation = validateAddressForm(config, format, state);
+  const custom: Record<string, string> = {};
+  for (const spec of config.customFields ?? []) {
+    const value = state.custom[spec.key]?.trim();
+    if (value) custom[spec.key] = value;
+  }
+  // The payload carries only what the CURRENT plan collects — a scope narrowing must not keep
+  // emitting fields the form no longer shows. State retains the values, so widening back
+  // restores them.
+  const planned = new Set<string>(planFields(config, format).gridFields);
+  return {
+    complete: validation.complete,
+    address: emitAddress(format, {
+      name: config.name === 'combined' ? state.values.name : undefined,
+      first_name: config.name === 'split' ? state.values.first_name : undefined,
+      last_name: config.name === 'split' ? state.values.last_name : undefined,
+      organization: config.organization === 'none' ? undefined : state.values.organization,
+      organization_type: config.organization === 'name_with_type' ? state.organizationType : '',
+      line1: planned.has('line1') ? state.values.line1 : undefined,
+      line2: planned.has('line1') && config.line2 !== 'never' ? state.values.line2 : undefined,
+      city: planned.has('city') ? state.values.city : undefined,
+      state: planned.has('state') ? state.values.state : undefined,
+      postal_code: planned.has('postal_code') ? state.values.postal_code : undefined,
+    }),
+    custom,
+    errors: validation.errors,
+  };
+}

package/src/core/address/places.ts

@@ -0,0 +1,39 @@
+// the shape ported from frontend/apps/web/src/elements/address-form/places.ts; the Google Places
+// loader around it is browser-only and has no counterpart here
+
+/** A resolved suggestion, in the same wire keys the address form emits. */
+export interface ParsedPlaceAddress {
+	line1?: string;
+	line2?: string;
+	city?: string;
+	state?: string;
+	postal_code?: string;
+	country?: string;
+}
+
+/**
+ * The country the buyer is dialling from, used as the address form's default before the buyer picks
+ * one. A miss falls through to `countryHint` and then US.
+ *
+ * Cloudflare's trace endpoint, which is what the web element reads — it uses the same-origin
+ * `/cdn-cgi/trace` because every rail it ships on sits behind Cloudflare. A native app has no
+ * origin, so this asks whop.com for the same thing.
+ *
+ * The previous port invented `https://whop.com/api/geo/`, which has never existed: it 404s (and
+ * `/api/geo` merely redirects to the same 404), so detection silently failed for every buyer and
+ * the form always opened on US.
+ */
+export async function detectIpCountry(timeoutMs = 1500): Promise<string | undefined> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch('https://whop.com/cdn-cgi/trace', { signal: controller.signal });
+		if (!response.ok) return undefined;
+		const country = /(?:^|\n)loc=([A-Za-z]{2})/.exec(await response.text())?.[1];
+		return country ? country.toUpperCase() : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/src/core/address/suggest.ts

@@ -0,0 +1,153 @@
+import type { ParsedPlaceAddress } from './places';
+
+/** One row in the suggestion list. Display only — components arrive from `resolve`. */
+export interface AddressSuggestion {
+	id: string;
+	label: string;
+}
+
+/** The raw components a resolved pick carries, before per-country composition. */
+export interface RawComponents {
+	streetNumber?: string;
+	street?: string;
+	/** Set only when the platform had no street components but did name the place. */
+	line1?: string;
+	city?: string;
+	state?: string;
+	postalCode?: string;
+	country?: string;
+}
+
+/**
+ * Where the house number leads the street name. Everywhere else it trails, and emitting
+ * "77 Unter den Linden" for a Berlin address is both wrong and an AVS mismatch.
+ *
+ * Both platform geocoders hand back the number and the street as separate components without an
+ * opinion on order, so this table is the only thing that decides it — which is why it lives here
+ * once rather than in Swift and Kotlin twice.
+ */
+const NUMBER_FIRST = new Set([
+	'US',
+	'CA',
+	'GB',
+	'IE',
+	'AU',
+	'NZ',
+	'IN',
+	'PH',
+	'MY',
+	'SG',
+	'ZA',
+	'JP',
+	'CN',
+	'KR',
+	'TW',
+	'HK',
+	'TH',
+	'VN',
+	'ID',
+]);
+
+/**
+ * Empty string is NOT absence, and the reducer cannot tell the difference: `apply-place` does
+ * `line1: parsed.line1 ?? state.values.line1`, so an empty line1 would REPLACE the street the
+ * buyer already typed, and `country: parsed.country ?? state.country` would blank the country.
+ * Both geocoders return "" for missing components, so this normalization is load-bearing.
+ */
+function present(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+export function composeLine1(
+	streetNumber: string | undefined,
+	street: string | undefined,
+	country: string | undefined,
+): string | undefined {
+	const number = present(streetNumber);
+	const name = present(street);
+	if (!name) return number;
+	if (!number) return name;
+	return NUMBER_FIRST.has((country ?? '').toUpperCase()) ? `${number} ${name}` : `${name} ${number}`;
+}
+
+/** The suggestion rows a `suggest` call returned. */
+export function parseSuggestions(json: string): AddressSuggestion[] {
+	let rows: unknown;
+	try {
+		rows = JSON.parse(json);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(rows)) return [];
+	return rows
+		.filter(
+			(row): row is AddressSuggestion =>
+				typeof row === 'object' && row !== null && typeof row.id === 'string' && typeof row.label === 'string',
+		)
+		.filter((row) => row.id.length > 0 && row.label.length > 0);
+}
+
+/**
+ * A resolved pick, in the wire keys the address form emits.
+ *
+ * `formCountry` backfills a resolve that names no country, which both geocoders do occasionally.
+ * Without it `composeLine1` orders the street as if it were number-last, and `placeAllowed` rejects
+ * a country-less parse whenever an allow list is active — so the pick silently no-ops.
+ */
+export function parseComponents(json: string, formCountry?: string): ParsedPlaceAddress | null {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch {
+		return null;
+	}
+	if (typeof raw !== 'object' || raw === null) return null;
+	const row = raw as RawComponents;
+
+	const country = present(row.country)?.toUpperCase() ?? present(formCountry)?.toUpperCase();
+	const line1 = composeLine1(row.streetNumber, row.street, country) ?? present(row.line1);
+	// Without a street the whole-replace in `apply-place` would clear the grid in exchange for
+	// nothing, so a componentless resolve declines instead.
+	if (!line1) return null;
+
+	return {
+		line1,
+		city: present(row.city),
+		state: present(row.state),
+		postal_code: present(row.postalCode),
+		country,
+	};
+}
+
+/**
+ * A geocoder's subdivision, as the catalog key the address engine validates against.
+ *
+ * The engine keys subdivisions by `sub_key` and builds each option's display name by joining the
+ * native and latin names — `[names[i] || key, latinNames[i]].join(' — ')` at
+ * core/address/engine.ts:141, so Tokyo's option is key `東京都` and name `東京都 — Tokyo`. A geocoder
+ * answers with ONE of those halves and never the joined form, so matching the whole `name` string
+ * misses every country whose catalog carries both scripts.
+ *
+ * An unmatched value resolves to undefined rather than to itself: it would render the state Select
+ * on its placeholder while still being emitted, so `apply-place` writing '' and surfacing the
+ * required-state error is the honest outcome.
+ */
+export function resolveSubdivision(
+	value: string | undefined,
+	options: { key: string; name: string; iso?: string }[],
+): string | undefined {
+	const wanted = present(value)?.toLowerCase();
+	if (!wanted) return undefined;
+	if (options.length === 0) return present(value);
+	return options.find((option) => subdivisionAliases(option).includes(wanted))?.key;
+}
+
+/** Kept identical to the separator engine.ts:141 joins with. */
+const NAME_SEPARATOR = ' — ';
+
+function subdivisionAliases(option: { key: string; name: string; iso?: string }): string[] {
+	return [option.key, option.iso, option.name, ...option.name.split(NAME_SEPARATOR)]
+		.map((part) => present(part)?.toLowerCase())
+		.filter((part): part is string => part !== undefined);
+}