@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/steps/AddressInfoStep.tsx

@@ -0,0 +1,726 @@
+/**
+ * ADDRESS_INFO — POST /sessions/:id/address-info.
+ *
+ * Two flows:
+ *
+ *   1. **Assisted** (when `VelionConfig.googleMapsApiKey` is set, or on iOS
+ *      where Apple Maps needs no key): intro → map picker → details (floor /
+ *      apartment / references) → submit. Lat/Lng are included in the payload.
+ *   2. **Manual** (default fallback): the structured form — country, state,
+ *      city, district, neighborhood, street, number, zip, plus the same
+ *      details fields. No lat/lng.
+ *
+ * The orchestrator picks the flow by passing `googleMapsApiKey` through
+ * `StepDeps`; the step itself decides which view to mount.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { Platform, StyleSheet, Text, View } from 'react-native';
+import {
+  SdkErrorCode,
+  type AddressInfoPayload,
+  type AddressInfoStepConfig,
+  type SdkError,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { CountrySelect } from '../ui/primitives/CountrySelect';
+import { Input } from '../ui/primitives/Input';
+import { LoadingOverlay } from '../ui/overlays/LoadingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { HomeHeartIcon } from '../ui/icons/HomeHeartIcon';
+import { MapFallbackBoundary } from '../ui/MapFallbackBoundary';
+import { useTheme } from '../ui/theme';
+import { getStrings } from '../i18n';
+import { MapAddressPicker } from '../camera/MapAddressPicker';
+import type { ParsedAddressFields } from '../utils/parseGoogleAddressComponents';
+import type { ApiCaller } from '../transport/api';
+import {
+  isReactNativeMapsAvailable,
+  isAndroidGoogleMapsKeyInManifest,
+} from '../utils/googleMapsPreflight';
+import { log } from '../utils/log';
+import type { StepDeps, StepModule } from './types';
+import { toSubmissionError } from './_shared';
+
+const ADDRESS_TYPE_HOME = 'HOME';
+
+export class AddressInfoStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <AddressInfoView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          stepConfig={this.deps.stepConfig as AddressInfoStepConfig | undefined}
+          googleMapsApiKey={this.deps.googleMapsApiKey}
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  stepConfig: AddressInfoStepConfig | undefined;
+  googleMapsApiKey: string | undefined;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+/**
+ * Resolves which sub-flow to mount.
+ *
+ *   - `assisted`: react-native-maps is linked AND the platform can render the
+ *                 map without extra config. iOS uses Apple Maps (no API key
+ *                 needed); Android uses Google Maps (requires the integrator
+ *                 to declare the key in AndroidManifest, which we approximate
+ *                 by requiring `googleMapsApiKey` in VelionConfig — without
+ *                 it the MapView would render blank).
+ *   - `manual`:   native module missing, OR Android without an API key, OR
+ *                 the map component threw at render time (caught by
+ *                 `MapFallbackBoundary` and bubbled here via `setMode`).
+ */
+type AddressFlowMode = 'assisted' | 'manual';
+
+function AddressInfoView(props: ViewProps) {
+  const hasApiKey =
+    typeof props.googleMapsApiKey === 'string' &&
+    props.googleMapsApiKey.trim().length > 0;
+
+  const [mode, setMode] = useState<AddressFlowMode>(() => {
+    if (!isReactNativeMapsAvailable()) {
+      log.warn(
+        '[address] react-native-maps native module unavailable; falling back to manual form',
+      );
+      return 'manual';
+    }
+    // Android requires the Maps SDK API key in the manifest — without it the
+    // <MapView> renders blank. iOS uses Apple Maps and needs no key at all.
+    if (Platform.OS === 'android' && !hasApiKey) {
+      log.info(
+        '[address] no googleMapsApiKey configured; Android cannot render the assisted map, using manual form',
+      );
+      return 'manual';
+    }
+    // Android meta-data probe. The JS-side `googleMapsApiKey` does NOT reach
+    // Google Maps SDK — the SDK reads the key from AndroidManifest.xml at
+    // mount time. If the host forgot to declare it there (e.g. set the key in
+    // VelionConfig but not in `app.config.js → android.config.googleMaps.apiKey`)
+    // mounting <MapView> throws a native IllegalStateException that no JS
+    // boundary can catch. Detect the mismatch and degrade gracefully.
+    if (Platform.OS === 'android' && hasApiKey) {
+      const inManifest = isAndroidGoogleMapsKeyInManifest();
+      if (inManifest === false) {
+        log.warn(
+          '[address] googleMapsApiKey is set in VelionConfig but the Android manifest does not declare ' +
+            '`com.google.android.geo.API_KEY`. Add it via app.config.js → android.config.googleMaps.apiKey ' +
+            'and re-run `expo prebuild`. Falling back to the manual form to prevent a native crash.',
+        );
+        return 'manual';
+      }
+    }
+    return 'assisted';
+  });
+
+  if (mode === 'assisted') {
+    return (
+      <AssistedAddressFlow
+        {...props}
+        onMapRenderFailure={() => {
+          log.warn(
+            '[address] map render threw at runtime; switching to manual form',
+          );
+          setMode('manual');
+        }}
+      />
+    );
+  }
+
+  return <ManualAddressForm {...props} />;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ASSISTED FLOW — intro → map picker → details
+// ─────────────────────────────────────────────────────────────────────────────
+
+type AssistedPhase = 'intro' | 'map' | 'details';
+
+interface AssistedProps extends ViewProps {
+  /** Called when the MapView crashes at render time (e.g. AirGoogleMaps missing on iOS). */
+  onMapRenderFailure: () => void;
+}
+
+function AssistedAddressFlow({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+  onMapRenderFailure,
+}: AssistedProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  const [phase, setPhase] = useState<AssistedPhase>('intro');
+  const [parsed, setParsed] = useState<
+    (ParsedAddressFields & { latitude: number; longitude: number }) | null
+  >(null);
+
+  const requiredFields = useMemo(() => {
+    const f = stepConfig?.fields;
+    return {
+      state: f?.state?.required !== false,
+      city: f?.city?.required !== false,
+      street: f?.street?.required !== false,
+      number: f?.number?.required !== false,
+      postal: f?.postal_code?.required !== false,
+    };
+  }, [stepConfig?.fields]);
+
+  if (phase === 'intro') {
+    return (
+      <View style={{ flex: 1 }}>
+        <StepShell
+          title={t.address_info.introTitle}
+          subtitle={t.address_info.introLine1}
+          iconNode={<HomeHeartIcon />}
+        >
+          <Text style={[styles.introBody, { color: theme.textSecondaryColor }]}>
+            {t.address_info.introLine2}
+          </Text>
+          <Button
+            label={t.address_info.introNext}
+            onPress={() => setPhase('map')}
+          />
+        </StepShell>
+      </View>
+    );
+  }
+
+  if (phase === 'map') {
+    return (
+      <MapFallbackBoundary onError={onMapRenderFailure}>
+        <MapAddressPicker
+          locale={locale}
+          nextLabel={t.address_info.mapNext}
+          backLabel={t.address_info.mapBack}
+          searchPlaceholder={t.address_info.mapSearchPlaceholder}
+          searchingLabel={t.address_info.mapSearching}
+          noResultsLabel={t.address_info.mapNoResults}
+          geocodeError={t.address_info.geocodeError}
+          locationDenied={t.address_info.locationDenied}
+          requiredFields={requiredFields}
+          countryAllow={stepConfig?.country_allow}
+          onConfirm={(p) => {
+            setParsed(p);
+            setPhase('details');
+          }}
+          onBack={() => setPhase('intro')}
+        />
+      </MapFallbackBoundary>
+    );
+  }
+
+  if (!parsed) {
+    setPhase('map');
+    return <View />;
+  }
+  return (
+    <AddressDetailsForm
+      api={api}
+      sessionId={sessionId}
+      locale={locale}
+      parsed={parsed}
+      addressType={stepConfig?.address_type?.id ?? ADDRESS_TYPE_HOME}
+      onComplete={onComplete}
+      onCancel={onCancel}
+      onBack={() => setPhase('map')}
+    />
+  );
+}
+
+interface DetailsFormProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  parsed: ParsedAddressFields & { latitude: number; longitude: number };
+  addressType: string;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+  onBack: () => void;
+}
+
+function AddressDetailsForm({
+  api,
+  sessionId,
+  locale,
+  parsed,
+  addressType,
+  onComplete,
+  onCancel,
+  onBack,
+}: DetailsFormProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  const [floor, setFloor] = useState('');
+  const [apartment, setApartment] = useState('');
+  const [details, setDetails] = useState('');
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    const payload: AddressInfoPayload = {
+      type: addressType,
+      country: parsed.country,
+      state: parsed.state,
+      city: parsed.city,
+      street: parsed.street,
+      number: parsed.number,
+      zip_code: parsed.zip_code,
+      latitude: parsed.latitude,
+      longitude: parsed.longitude,
+      ...(parsed.district && { district: parsed.district }),
+      ...(parsed.neighborhood && { neighborhood: parsed.neighborhood }),
+      ...(floor.trim() && { floor: floor.trim() }),
+      ...(apartment.trim() && { apartment: apartment.trim() }),
+      ...(details.trim() && { details: details.trim() }),
+    };
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/address-info`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [
+    addressType,
+    api,
+    apartment,
+    details,
+    floor,
+    onComplete,
+    parsed,
+    sessionId,
+    t,
+  ]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({ code: SdkErrorCode.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.address_info.detailsTitle}
+        subtitle={parsed.street ? `${parsed.street} ${parsed.number}` : undefined}
+        iconNode={<HomeHeartIcon />}
+      >
+        <Text style={[styles.summary, { color: theme.textSecondaryColor }]}>
+          {parsed.city}
+          {parsed.state ? `, ${parsed.state}` : ''} ({parsed.country})
+        </Text>
+        <View style={styles.row}>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.floor}
+              autoCorrect={false}
+              value={floor}
+              onChangeText={setFloor}
+            />
+          </View>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.apartment}
+              autoCorrect={false}
+              value={apartment}
+              onChangeText={setApartment}
+            />
+          </View>
+        </View>
+        <Input
+          label={t.address_info.references}
+          autoCorrect
+          multiline
+          numberOfLines={3}
+          value={details}
+          onChangeText={setDetails}
+        />
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <View style={styles.row}>
+          <Button
+            variant="ghost"
+            label={t.address_info.mapBack}
+            onPress={onBack}
+            fullWidth={false}
+            style={styles.col}
+          />
+          <Button
+            label={t.common.continue}
+            onPress={handleSubmit}
+            loading={submitting}
+            disabled={submitting}
+            fullWidth={false}
+            style={styles.col}
+          />
+        </View>
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MANUAL FLOW — structured form, kept side-by-side with the assisted flow so
+// consumers without a Maps key still get a full onboarding experience.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type FieldKey =
+  | 'country'
+  | 'state'
+  | 'city'
+  | 'district'
+  | 'neighborhood'
+  | 'street'
+  | 'number'
+  | 'zip_code'
+  | 'floor'
+  | 'apartment'
+  | 'details';
+
+type ManualForm = Record<FieldKey, string>;
+
+const INITIAL_MANUAL: ManualForm = {
+  country: '',
+  state: '',
+  city: '',
+  district: '',
+  neighborhood: '',
+  street: '',
+  number: '',
+  zip_code: '',
+  floor: '',
+  apartment: '',
+  details: '',
+};
+
+function ManualAddressForm({
+  api,
+  sessionId,
+  locale,
+  stepConfig,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const f = stepConfig?.fields;
+
+  const allowedCodes = useMemo(() => {
+    const allow = stepConfig?.country_allow;
+    if (!Array.isArray(allow) || allow.length === 0) return undefined;
+    return allow.map((c) => c.toUpperCase());
+  }, [stepConfig?.country_allow]);
+
+  const requirements = useMemo(
+    () => ({
+      state: f?.state?.required !== false,
+      city: f?.city?.required !== false,
+      district: f?.district?.required === true,
+      neighborhood: f?.neighborhood?.required === true,
+      street: f?.street?.required !== false,
+      number: f?.number?.required !== false,
+      zip: f?.postal_code?.required !== false,
+    }),
+    [f],
+  );
+
+  const [form, setForm] = useState<ManualForm>(() => {
+    const base = { ...INITIAL_MANUAL };
+    if (allowedCodes && allowedCodes.length === 1) {
+      base.country = allowedCodes[0] ?? '';
+    }
+    return base;
+  });
+
+  useEffect(() => {
+    if (allowedCodes && allowedCodes.length === 1 && !form.country) {
+      setForm((prev) => ({ ...prev, country: allowedCodes[0] ?? '' }));
+    }
+  }, [allowedCodes, form.country]);
+
+  const [errors, setErrors] = useState<Partial<Record<FieldKey, string>>>({});
+  const [bannerError, setBannerError] = useState<string | null>(null);
+  const [submitting, setSubmitting] = useState(false);
+  const [retry, setRetry] = useState<{ message: string } | null>(null);
+
+  const setField = useCallback((key: FieldKey, value: string) => {
+    setForm((prev) => ({ ...prev, [key]: value }));
+    setErrors((prev) => {
+      if (!(key in prev)) return prev;
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+  }, []);
+
+  const validate = useCallback((): boolean => {
+    const next: Partial<Record<FieldKey, string>> = {};
+    if (!form.country) next.country = t.address_info.requiredCountry;
+    if (requirements.state && !form.state.trim())
+      next.state = t.address_info.requiredState;
+    if (requirements.city && !form.city.trim())
+      next.city = t.address_info.requiredCity;
+    if (requirements.district && !form.district.trim())
+      next.district = t.address_info.requiredDistrict;
+    if (requirements.neighborhood && !form.neighborhood.trim())
+      next.neighborhood = t.address_info.requiredNeighborhood;
+    if (requirements.street && !form.street.trim())
+      next.street = t.address_info.requiredStreet;
+    if (requirements.number && !form.number.trim())
+      next.number = t.address_info.requiredNumber;
+    if (requirements.zip && !form.zip_code.trim())
+      next.zip_code = t.address_info.requiredZip;
+    setErrors(next);
+    return Object.keys(next).length === 0;
+  }, [form, requirements, t.address_info]);
+
+  const handleSubmit = useCallback(async () => {
+    setBannerError(null);
+    if (!validate()) {
+      setBannerError(t.address_info.fillAllRequired);
+      return;
+    }
+    const payload: AddressInfoPayload = {
+      type: stepConfig?.address_type?.id ?? ADDRESS_TYPE_HOME,
+      country: form.country.toUpperCase(),
+      state: form.state.trim(),
+      city: form.city.trim(),
+      street: form.street.trim(),
+      number: form.number.trim(),
+      zip_code: form.zip_code.trim(),
+      ...(form.district.trim() && { district: form.district.trim() }),
+      ...(form.neighborhood.trim() && { neighborhood: form.neighborhood.trim() }),
+      ...(form.floor.trim() && { floor: form.floor.trim() }),
+      ...(form.apartment.trim() && { apartment: form.apartment.trim() }),
+      ...(form.details.trim() && { details: form.details.trim() }),
+    };
+    setSubmitting(true);
+    try {
+      await api.post(`/sessions/${sessionId}/address-info`, payload);
+      setSubmitting(false);
+      onComplete();
+    } catch (err) {
+      setSubmitting(false);
+      const sdkErr = toSubmissionError(err, t);
+      setBannerError(sdkErr.message);
+      setRetry({ message: sdkErr.message });
+    }
+  }, [api, form, onComplete, sessionId, stepConfig?.address_type?.id, t, validate]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.common.submissionTitle}
+        message={retry.message || t.common.submissionFallback}
+        retryLabel={t.common.retry}
+        cancelLabel={t.common.cancel}
+        onRetry={() => setRetry(null)}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({ code: SdkErrorCode.API_ERROR, message: retry.message });
+        }}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <StepShell
+        title={t.address_info.title}
+        subtitle={t.address_info.subtitle}
+        iconNode={<HomeHeartIcon />}
+      >
+        <CountrySelect
+          label={t.address_info.country}
+          required
+          value={form.country || null}
+          onChange={(v) => setField('country', v)}
+          locale={locale}
+          allowedCodes={allowedCodes}
+          placeholder={t.address_info.countryPlaceholder}
+          searchPlaceholder={t.address_info.countryPlaceholder}
+          errorMessage={errors.country ?? null}
+        />
+        <Input
+          label={t.address_info.state}
+          required={requirements.state}
+          autoCapitalize="words"
+          autoCorrect={false}
+          value={form.state}
+          onChangeText={(v) => setField('state', v)}
+          errorMessage={errors.state ?? null}
+        />
+        <Input
+          label={t.address_info.city}
+          required={requirements.city}
+          autoCapitalize="words"
+          autoCorrect={false}
+          value={form.city}
+          onChangeText={(v) => setField('city', v)}
+          errorMessage={errors.city ?? null}
+        />
+        <Input
+          label={t.address_info.district}
+          required={requirements.district}
+          autoCapitalize="words"
+          autoCorrect={false}
+          value={form.district}
+          onChangeText={(v) => setField('district', v)}
+          errorMessage={errors.district ?? null}
+        />
+        <Input
+          label={t.address_info.neighborhood}
+          required={requirements.neighborhood}
+          autoCapitalize="words"
+          autoCorrect={false}
+          value={form.neighborhood}
+          onChangeText={(v) => setField('neighborhood', v)}
+          errorMessage={errors.neighborhood ?? null}
+        />
+        <Input
+          label={t.address_info.street}
+          required={requirements.street}
+          autoCapitalize="words"
+          autoCorrect={false}
+          value={form.street}
+          onChangeText={(v) => setField('street', v)}
+          errorMessage={errors.street ?? null}
+        />
+        <View style={styles.row}>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.number}
+              required={requirements.number}
+              keyboardType="number-pad"
+              autoCorrect={false}
+              value={form.number}
+              onChangeText={(v) => setField('number', v)}
+              errorMessage={errors.number ?? null}
+            />
+          </View>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.zipCode}
+              required={requirements.zip}
+              autoCapitalize="characters"
+              autoCorrect={false}
+              value={form.zip_code}
+              onChangeText={(v) => setField('zip_code', v)}
+              errorMessage={errors.zip_code ?? null}
+            />
+          </View>
+        </View>
+        <View style={styles.row}>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.floor}
+              autoCorrect={false}
+              value={form.floor}
+              onChangeText={(v) => setField('floor', v)}
+            />
+          </View>
+          <View style={styles.col}>
+            <Input
+              label={t.address_info.apartment}
+              autoCorrect={false}
+              value={form.apartment}
+              onChangeText={(v) => setField('apartment', v)}
+            />
+          </View>
+        </View>
+        <Input
+          label={t.address_info.references}
+          autoCorrect
+          multiline
+          numberOfLines={3}
+          value={form.details}
+          onChangeText={(v) => setField('details', v)}
+        />
+        {bannerError ? <Banner message={bannerError} /> : null}
+        <Button
+          label={t.common.continue}
+          onPress={handleSubmit}
+          loading={submitting}
+          disabled={submitting}
+        />
+      </StepShell>
+      {submitting ? <LoadingOverlay message={t.common.submitting} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    gap: 8,
+  },
+  col: {
+    flex: 1,
+  },
+  introBody: {
+    fontSize: 14,
+    lineHeight: 20,
+    textAlign: 'center',
+    marginVertical: 12,
+  },
+  summary: {
+    fontSize: 13,
+    textAlign: 'center',
+    marginBottom: 8,
+  },
+});