npm package: @grdistro/store-locator-widget
Description: A modular store locator widget with Mapbox integration that can be embedded in any website
Author: Store Locator Team
Latest version: 1.0.0

# Store Locator Widget

A modular, embeddable store locator widget that can be easily integrated into any website.

[![npm version](https://badge.fury.io/js/@your-org%2Fstore-locator-widget.svg)](https://badge.fury.io/js/@your-org%2Fstore-locator-widget)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🗺️ Interactive map integration (Mapbox support)
- 🔍 Store search and filtering
- 📍 Geolocation support
- 📱 Mobile responsive design
- 🎨 Customizable themes and styling
- 🔧 Simple JavaScript API
- 🚀 Easy integration with any website

## Installation

### NPM Installation

```bash
npm install @your-org/store-locator-widget
```

### CDN Usage

```html
<script src="https://unpkg.com/@your-org/store-locator-widget@latest/store-locator.min.js"></script>
```

### Download and Host

Download the latest release and include the script:

```html
<script src="store-locator.js"></script>
```

## Quick Start

### NPM Usage

```javascript
import StoreLocator from '@your-org/store-locator-widget';

const storeLocator = new StoreLocator({
  containerId: 'store-locator',
  stores: [/* your stores */]
});
```

### Script Tag Usage

### 2. Create a Container

```html
<div id="store-locator"></div>
```

### 3. Initialize the Widget

```javascript
const storeLocator = new StoreLocator({
    containerId: 'store-locator',
    stores: [
        {
            id: 1,
            name: 'Store Name',
            address: '123 Main St, City, State 12345',
            phone: '(555) 123-4567',
            latitude: '40.7580',
            longitude: '-73.9855',
            isOpen: true
        }
    ]
});
```

## Configuration Options

```javascript
const config = {
    // Required
    containerId: 'store-locator',        // ID of container element
    
    // Store Data
    stores: [],                          // Array of store objects
    apiEndpoint: '/api/stores',          // API endpoint for loading stores
    
    // Map Configuration
    mapboxToken: 'your-token',           // Mapbox access token
    
    // UI Options
    height: '600px',                     // Widget height
    showSearch: true,                    // Show search bar
    showFilters: true,                   // Show filter buttons
    showMap: true,                       // Show map component
    theme: 'light',                      // Theme: 'light' or 'dark'
    
    // Callbacks
    onStoreSelect: (store) => {},        // Called when store is selected
};
```

## Store Object Format

```javascript
{
    id: 1,                              // Unique identifier
    name: 'Store Name',                 // Store name
    address: '123 Main St...',          // Full address
    phone: '(555) 123-4567',           // Phone number
    latitude: '40.7580',               // Latitude coordinate
    longitude: '-73.9855',             // Longitude coordinate
    isOpen: true,                      // Current open status
    // Optional fields
    website: 'https://...',            // Store website
    hours: {...},                      // Operating hours
    services: [],                      // Available services
}
```

## API Methods

```javascript
// Add a new store
storeLocator.addStore(storeObject);

// Remove a store
storeLocator.removeStore(storeId);

// Update store information
storeLocator.updateStore(storeId, updates);

// Get currently selected store
const selected = storeLocator.getSelectedStore();

// Destroy the widget
storeLocator.destroy();
```

## Events

```javascript
// Listen for store selection
document.getElementById('store-locator').addEventListener('storeSelect', (event) => {
    console.log('Selected store:', event.detail.store);
});
```

## Integration Examples

### Basic Integration
```html
<!DOCTYPE html>
<html>
<head>
    <title>My Store Locator</title>
</head>
<body>
    <div id="store-locator"></div>
    
    <script src="store-locator.js"></script>
    <script>
        new StoreLocator({
            containerId: 'store-locator',
            stores: [/* your stores */]
        });
    </script>
</body>
</html>
```

### With API Integration
```javascript
const storeLocator = new StoreLocator({
    containerId: 'store-locator',
    apiEndpoint: 'https://api.yoursite.com/stores',
    mapboxToken: 'your-mapbox-token',
    onStoreSelect: (store) => {
        // Track analytics
        gtag('event', 'store_select', {
            store_id: store.id,
            store_name: store.name
        });
    }
});
```

### Shopify Integration
```liquid
<!-- In your Shopify template -->
<div id="shopify-store-locator"></div>

<script src="{{ 'store-locator.js' | asset_url }}"></script>
<script>
    const storeLocator = new StoreLocator({
        containerId: 'shopify-store-locator',
        apiEndpoint: '/apps/store-locator/api/stores',
        theme: '{{ settings.theme_style }}',
        onStoreSelect: (store) => {
            // Shopify analytics
            analytics.track('Store Selected', {
                store_id: store.id,
                store_name: store.name
            });
        }
    });
</script>
```

### WordPress Integration
```php
// In your WordPress theme
function enqueue_store_locator() {
    wp_enqueue_script('store-locator', get_template_directory_uri() . '/js/store-locator.js');
}
add_action('wp_enqueue_scripts', 'enqueue_store_locator');
```

```html
<!-- In your template -->
<div id="wp-store-locator"></div>

<script>
    document.addEventListener('DOMContentLoaded', function() {
        new StoreLocator({
            containerId: 'wp-store-locator',
            apiEndpoint: '<?php echo admin_url('admin-ajax.php'); ?>?action=get_stores',
        });
    });
</script>
```

## Styling

The widget uses CSS custom properties for easy theming:

```css
:root {
    --primary-color: #3b82f6;
    --secondary-color: #64748b;
    --background-color: #ffffff;
    --border-color: #e2e8f0;
    --text-color: #1f2937;
}
```

## Browser Support

- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+

## License

MIT License - feel free to use in commercial and personal projects.