> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velure.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Location Input

> InputLocation.vue Component Documentation

The `InputLocation.vue` component is a Vue.js Composition API-based component that integrates Google Maps functionality. It is designed for capturing and interacting with location data, including countries, states, cities, and geographic coordinates.

***

## Features

<CardGroup cols={2}>
  <Card title="Dynamic Field Rendering" icon="square-1">
    Conditionally display fields based on provided props (e.g., countries, states, coordinates).
  </Card>

  <Card title="Google Maps Integration" icon="square-2">
    Includes a map view and coordinate management.
  </Card>

  <Card title="Customizable Inputs" icon="square-3">
    Supports v-model binding and dynamic event handling.
  </Card>

  <Card title="Validation Support" icon="square-4">
    Displays errors for each input field.
  </Card>

  <Card title="Debounced Input Events" icon="square-5">
    Reduces unnecessary updates for text inputs.
  </Card>
</CardGroup>

***

## Usage

### Basic Example

```js theme={null}
import { InputLocation } from '@robojuice/velure-ui';
```

```vue theme={null}
<InputLocation
  @keyup="locationFieldType"
  @change="locationFieldChange"
  v-model="locationField"
  coordinates
  :countries="['USA']"
  :statesShape="{value: 'abbreviation', text: 'name'}"
  :states="states"
/>
```

### Custom States Example

```vue theme={null}
<InputLocation
  @keyup="locationFieldType"
  @change="locationFieldChange"
  v-model="locationField"
  :states="['CA', 'NY', 'FL']"
/>
```

The `locationField` model is a reactive object in Vue.js designed to represent and manage the state of location data. It includes fields for address details, geographic coordinates, and other related information.

***

## Data Structure

The `locationField` model for the `v-model` consists of the following properties:

### Properties

<ParamField path="address1" type="string" default="''">
  The primary address or street name.
</ParamField>

<ParamField path="address2" type="string" default="''">
  Additional address details (e.g., apartment, suite).
</ParamField>

<ParamField path="city" type="string" default="''">
  The name of the city.
</ParamField>

<ParamField path="state" type="string" default="''">
  The state or region.
</ParamField>

<ParamField path="zip" type="string" default="''">
  The postal or ZIP code.
</ParamField>

<ParamField path="country" type="string" default="''">
  The country name or code.
</ParamField>

<ParamField path="lat" type="string" default="''">
  The latitude coordinate.
</ParamField>

<ParamField path="lng" type="string" default="''">
  The longitude coordinate.
</ParamField>

To create and use the `locationField` model in your Vue.js component, import and initialize it as follows:

```vue theme={null}
<script setup>
import { reactive } from 'vue';

const locationField = reactive({
  address1: '',
  address2: '',
  city: '',
  state: '',
  zip: '',
  country: '',
  lat: '',
  lng: '',
});
</script>
```

***

## Props

<ParamField path="v-model" type="object" default="undefined">
  The value bound to each input field.
</ParamField>

<ParamField path="width" type="number | string" default="100">
  The width of the component as a percentage.
</ParamField>

<ParamField path="mapClasses" type="string" default="''">
  CSS classes applied to the map container.
</ParamField>

<ParamField path="states" type="array | object" default="[]">
  List of states to populate the `State` dropdown.
</ParamField>

<ParamField path="statesShape" type="object" default="{}">
  Defines the key-value structure for state options.
</ParamField>

<ParamField path="countries" type="array | object" default="[]">
  List of countries to populate the `Country` dropdown.
</ParamField>

<ParamField path="countriesShape" type="object" default="{}">
  Defines the key-value structure for country options.
</ParamField>

<ParamField path="coordinates" type="boolean" default="false">
  Toggles latitude/longitude fields and map integration.
</ParamField>

<ParamField path="api" type="string" default="''">
  Google Maps API key for map functionality.
</ParamField>

<ParamField path="map" type="array | object" default="{zoom: 8, center: {...}}">
  Google Maps configuration object (e.g., zoom level, center coordinates).
</ParamField>

<ParamField path="errors" type="array" default="[]">
  Array of error messages for specific fields.
</ParamField>

### Sates & Countries

For the prop `statesShape` and `countriesShape`, the configuration looks like this: `{value: 'abbreviation', text: 'name' }`. And the data for the `states` or `countries` prop looks like this:

```js theme={null}
const states = [
  { name: 'Alabama', abbreviation: 'AL'},
  { name: 'Alaska', abbreviation: 'AK'},
  { name: 'American Samoa', abbreviation: 'AS'}
]

const countries = [
  { name: 'United Stats', abbreviation: 'USA'}
]
```

Within the component:

```vue theme={null}
<InputLocation
  :countries="countries"
  :statesShape="{value: 'abbreviation', text: 'name'}"
  :countriesShape="{value: 'abbreviation', text: 'name'}"
  :states="states"
/>
```

If you want to keep it simple, you can use an array of values and the shape props will not be required:

```js theme={null}
let states = ['AL','AK','AS'];
let countries = ['USA'];
```

Within the component:

```vue theme={null}
<InputLocation
  :countries="countries"
  :states="states"
/>
```

***

## Events

<ParamField path="keyup" type="event">
  Triggered when a key is released in an input field.
</ParamField>

<ParamField path="change" type="event">
  Triggered when a dropdown or input value changes.
</ParamField>

<ParamField path="blur" type="event">
  Triggered when an input field loses focus.
</ParamField>

<ParamField path="enter" type="event">
  Triggered when the Enter key is pressed in an input field.
</ParamField>

***

## Methods

### `loadCoordinates`

Loads the geographic coordinates (latitude/longitude) into the form fields.

### `clearCoordinates`

Clears the geographic coordinates from the form fields.

***

## Slots

This component does not use slots.

***

## Google Maps

Create or Access a Google Cloud Project

* Go to the [Google Cloud Console](https://console.cloud.google.com/).
* Sign in with your Google account.
* Create a new project or select an existing one.

A map ID is an identifier that's associated with a specific map style or feature. Configure a map style and associate it with a map ID in the Google Cloud Console. Then, when you reference a map ID in your code.

[Google documentation for using "Map IDs"](https://developers.google.com/maps/documentation/get-map-id)

### Implementation

The `map` prop should match the Google `MapOptions`, see the docs here [Google docs for MapOptions](https://developers.google.com/maps/documentation/javascript/reference/map#MapOptions).

```js theme={null}
const api_map_id = 'your_api_map_id_here';  // ADD MAP ID here from Google cloud console
const api_key = 'your_api_key_here';
const map_options = {
  zoom: 8, // 16 best
  center: {lat: 39.8283, lng: -98.5795},
  scrollwheel: false,
  disableDefaultUI: false,
  mapId: api_map_id
}
```

<Warning>You need `coordinates` on the component for Google Maps to get enabled.</Warning>

```vue theme={null}
<InputLocation
  coordinates
  :map="map_options"
  :key="api_key"
/>
```

## Notes

* Google Maps JavaScript API integration requires an API key (`api` prop).
* Fields such as `Country`, `State`, and `Coordinates` are rendered conditionally based on the provided props.