AddressField

AddressField renderiza un selector de ubicación de Google Maps junto con desplegables autocomplete en cascada (país, subdivisión, ciudad, barrio) e inputs de texto para calle, número, piso, departamento, código postal y notas. Cuando el usuario arrastra el marcador o busca una dirección, el componente hace geocodificación inversa y rellena los campos automáticamente.

Props

| Prop | Tipo | Requerido | Por defecto | Descripción | |------|------|-----------|-------------|-------------| | label | string | No | — | Etiqueta mostrada sobre el componente. | | description | string | No | — | Texto de ayuda mostrado debajo del componente. | | value | AddressValue | Sí | — | Objeto de dirección actual (ver forma AddressValue más abajo). | | onChange | (value: AddressValue) => void | Sí | — | Llamado con el objeto de dirección actualizado ante cualquier cambio. | | countrySearchPath | string | Sí | — | Ruta API para buscar países (ej. /v1/countries). | | subdivisionSearchPath | string | Sí | — | Ruta API para buscar provincias/estados. | | citySearchPath | string | Sí | — | Ruta API para buscar ciudades. | | neighborhoodSearchPath | string | Sí | — | Ruta API para buscar barrios. | | apiBaseUrl | string | No | urls.apiBase | URL base para todas las llamadas autocomplete. | | useAuthToken | boolean | No | true | Si se debe adjuntar el token de autenticación a las requests autocomplete. | | searchParam | string | No | 'search' | Nombre del parámetro de query-string usado para el término de búsqueda. | | itemLabelKey | string | No | 'name' | Clave del objeto resultado usada como etiqueta de visualización. | | itemIdKey | string | No | 'id' | Clave del objeto resultado usada como identificador. | | apiKey | string | No | keys.googleMaps | Clave de la API de Google Maps JavaScript. | | width | number \| string | No | '100%' | Ancho del contenedor del mapa. | | mapHeight | number \| string | No | 300 | Alto del mapa en píxeles. | | zoom | number | No | 14 | Nivel de zoom inicial del mapa. | | initialCenter | { lat: number; lng: number } | No | — | Sobreescribe el centro inicial del mapa. Por defecto usa las coordenadas en value. | | markerIdleSrc | string | No | '/assets/markers/idle.svg' | URL de la imagen del marcador en reposo. | | markerDraggingSrc | string | No | '/assets/markers/drag.svg' | URL de la imagen del marcador al arrastrar. | | inputPlaceholder | string | No | 'Buscar dirección...' | Placeholder del input de búsqueda del mapa. | | language | string | No | — | Código de idioma para el locale de Google Maps. | | region | string | No | — | Región para el sesgo de geocodificación de Google Maps. | | geocodeOnDragEnd | boolean | No | true | Si se realiza geocodificación inversa al soltar el marcador. | | extraInputs | ('block' \| 'lot' \| 'meter_number')[] | No | [] | Inputs opcionales adicionales a mostrar (manzana, lote, número de medidor). | | containerStyle | React.CSSProperties | No | — | Estilos del contenedor exterior. | | headerStyle | React.CSSProperties | No | — | Estilos del área de encabezado del campo. | | bodyStyle | React.CSSProperties | No | — | Estilos del área de cuerpo del campo. | | labelStyle | React.CSSProperties | No | — | Estilos del elemento de etiqueta. | | descriptionStyle | React.CSSProperties | No | — | Estilos del párrafo de descripción. | | className | string | No | — | Clase CSS del contenedor exterior. |

Forma de AddressValue

interface AddressValue {
  name?: string;
  street: string;
  number?: string;
  floor?: string;
  apartment?: string;
  block?: string;
  lot?: string;
  meter_number?: string;
  zone_id?: number | null;
  neighborhood_id?: number | null;
  city_id?: number | null;
  subdivision_id?: number | null;
  country_id?: number | null;
  neighborhood_name?: string;
  city_name?: string;
  subdivision_name?: string;
  country_name?: string;
  formatted_address?: string;
  latitude?: number | null;
  longitude?: number | null;
  postal_code?: string;
  notes?: string;
  country?: any | null;
  subdivision?: any | null;
  city?: any | null;
  neighborhood?: any | null;
}

Uso

Básico

import React, { useState } from 'react';
import AddressField from '@/components/fields/AddressField';

export default function Example() {
  const [address, setAddress] = useState({ street: '' });

  return (
    <AddressField
      label="Dirección de entrega"
      value={address}
      onChange={setAddress}
      countrySearchPath="/v1/countries"
      subdivisionSearchPath="/v1/subdivisions"
      citySearchPath="/v1/cities"
      neighborhoodSearchPath="/v1/neighborhoods"
    />
  );
}

Con inputs extra y altura de mapa personalizada

<AddressField
  label="Dirección del inmueble"
  value={address}
  onChange={setAddress}
  countrySearchPath="/v1/countries"
  subdivisionSearchPath="/v1/subdivisions"
  citySearchPath="/v1/cities"
  neighborhoodSearchPath="/v1/neighborhoods"
  mapHeight={400}
  zoom={16}
  extraInputs={['block', 'lot']}
/>