npm package: @ouigoo/location-picker
Description: Universal location picker library for Ouigoo ecosystem - works with React and vanilla JS
Author: Ouigoo Team
Latest version: 1.0.8

# @ouigoo/location-picker

A universal JavaScript library for location selection, compatible with React and Vanilla JS.

## 🚀 Features

- ✅ **Google Maps**: Full integration via Google Maps API
- ✅ **Geocoding**: Address ↔ coordinates conversion
- ✅ **Geolocation**: "My location" button
- ✅ **Satellite view**: Map/satellite toggle
- ✅ **Search**: Address search
- ✅ **Responsive**: Mobile-first design
- ✅ **Themes**: Customizable (ouigoo, dark, etc.)
- ✅ **Accessible**: Keyboard and screen reader support

## 📦 Installation

```bash
npm install @ouigoo/location-picker
```

## 🎯 Usage

### React

```jsx
import { OuigooLocationPicker } from '@ouigoo/location-picker/react';

function App() {
  const handleLocationSelect = (result) => {
    console.log('Selected location:', result);
    // result = {
    //   location: { lat: 6.129, lng: 1.215 },
    //   address: "5736+MGW, Rue Hodjeme, Lomé, Togo",
    //   name: "AMINOU-NÔ",
    //   city: "Lomé",
    //   state: "Région maritime",
    //   country: "TG",
    //   timestamp: "2024-01-15T10:30:00.000Z"
    // }
  };

  return (
    <OuigooLocationPicker
      apiKey="your-google-maps-api-key"
      onLocationSelect={handleLocationSelect}
      centerOnUserLocation={true}
      theme="ouigoo"
    />
  );
}
```

### Vanilla JS

```html
<div id="location-picker"></div>

<script src="./dist/vanilla.js"></script> 
<script>
  // Initialization
  OuigooLocationPicker.createLocationPicker({
    container: '#location-picker',
    apiKey: 'your-google-maps-api-key',
    centerOnUserLocation: true,
    onLocationSelect: function(result) {
      console.log('Selected location:', result);
      // result contains: location, address, name, city, state, country, timestamp
    }
  }).then(function(picker) {
    console.log('LocationPicker initialized');
  });
</script>
```


## ⚙️ Configuration

### Main Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `container` | string\|HTMLElement | - | (Required) CSS selector or DOM element for the container. |
| `apiKey` | string | '' | (Required) Google Maps API key. |
| `defaultCenter` | {lat, lng} | `{ lat: 6.29, lng: 1.79 }` | Default map center (Benin/Togo). |
| `defaultZoom` | number | `8.28` | Default map zoom level. |
| `locationZoom` | number | `17` | Zoom level applied after selecting a location. |
| `language` | string | `'fr'` | Interface and Google Maps results language. |
| `theme` | string | `'ouigoo'` | Visual theme (`'ouigoo'`, `'dark'`, or a custom class name). |
| `enableSatelliteView` | boolean | `true` | Enable satellite view button. |
| `enableMyLocation` | boolean | `true` | Enable geolocation button. |
| `enableSearch` | boolean | `true` | Enable address search bar. |
| `country` | string | `null` | Country code (e.g., 'TG') to center the map initially. |
| `centerOnUserLocation` | boolean | `false` | If `true`, attempts to center the map on the user's location at startup. |
| `confirmButtonStyle` | string | `'rectangle'` | Confirmation button style (`'rectangle'` or `'circular'`). |
| `allowedCountries` | string[] | `['TG', 'BJ', ...]` | List of country codes to restrict search. |

### Callbacks

| Callback | Parameters | Description |
|----------|------------|-------------|
| `onLocationSelect` | `(result)` | Location confirmed by the user. See [Result Structure](#result-structure) |
| `onAddressChange` | `(address)` | Address updated (displayed in the interface) |
| `onLoadingChange` | `(isLoading)` | Loading state |
| `onError` | `(error)` | Error occurred |

### Result Structure

When the user confirms a location, the returned `result` object contains the following properties:

```javascript
{
  location: {
    lat: 6.129654,      // Latitude
    lng: 1.215964       // Longitude
  },
  address: "5736+MGW, Rue Hodjeme, Lomé, Togo",  // Full formatted address
  name: "AMINOU-NÔ",                              // Place name (if available)
  city: "Lomé",                                   // City
  state: "Région maritime",                       // State/Region
  country: "TG",                                  // Country code (ISO 3166-1 alpha-2)
  timestamp: "2024-01-15T10:30:00.000Z"          // Confirmation date/time (ISO 8601)
}
```

**Important notes:**
- The `name` field contains the place name when selected via autocomplete or available in geocoding data
- If the name is not available, `name` will be an empty string `""`
- The `city` and `state` fields may be empty if the information is not available
- The `country` field contains the 2-letter country code (e.g., "TG" for Togo, "BJ" for Benin)
- The interface preferentially displays the `name` if available, otherwise the `address`

## 🎨 Themes

### Ouigoo Theme (default)
```css
.ouigoo-location-picker.ouigoo {
  --primary-color: #ff6600;
  --background-color: #ffffff;
}
```

### Dark Theme
```jsx
<LocationPicker theme="dark" />
```

### Custom Theme
```css
.ouigoo-location-picker.custom {
  --primary-color: #your-color;
  --background-color: #your-bg;
}
```

## 🔧 Advanced API

### React Hook

```jsx
import { useLocationPicker } from '@ouigoo/location-picker/react';

function MyComponent() {
  const {
    picker,
    isReady,
    createPicker,
    setLocation,
    getCurrentLocation,
    searchLocation
  } = useLocationPicker();

  useEffect(() => {
    createPicker({
      container: '#my-picker',
      apiKey: 'your-key'
    });
  }, []);

  const handleSearch = () => {
    searchLocation('Paris, France');
  };

  return (
    <div>
      <div id="my-picker" />
      <button onClick={handleSearch}>Search Paris</button>
    </div>
  );
}
```

### Programmatic Control (Vanilla)

```javascript
const picker = await OuigooLocationPicker.createLocationPicker({
  container: '#picker',
  apiKey: 'your-key'
});

// Set a location
picker.setLocation({ lat: 48.8566, lng: 2.3522 });

// Search
await picker.searchLocation('Cotonou');

// Get current position
picker.getCurrentLocation();

// Destroy instance
picker.destroy();
```


## 📱 Responsive Design

The library is mobile-first and adapts automatically:

- **Desktop**: Full interface with all controls
- **Tablet**: Touch-optimized interface
- **Mobile**: Simplified interface, touch controls

## ♿ Accessibility

- Full keyboard support
- Screen reader compatible
- Respected contrasts (WCAG 2.1)
- Visible focus on all elements


## 🏗️ Build

```bash
npm run build
```

Generates:
- `dist/vanilla.js` - Vanilla UMD version
- `dist/vanilla.esm.js` - Vanilla ES modules version
- `dist/react.js` - React UMD version
- `dist/react.esm.js` - React ES modules version

## 📄 License

MIT © Ouigoo Team

## 🤝 Contributing

1. Fork the project
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📞 Support

- 📧 Email: support@ouigoo.co
- 🐛 Issues: [GitHub Issues](https://github.com/ouigoo/location-picker/issues)