scribo-maps
Version:
Embeddable map widget for store locators
417 lines (323 loc) • 10.7 kB
Markdown
# 🗺️ Scribo Maps
An embeddable, responsive map widget for store locators and location-based applications. Built with Google Maps API and designed for easy integration into any website.
[](https://www.npmjs.com/package/scribo-maps)
[](https://www.npmjs.com/package/scribo-maps)
[](https://opensource.org/licenses/MIT)
## ✨ Features
- 🌍 **Interactive Google Maps** with marker clustering
- 🔍 **Smart search** with Google Places autocomplete
- 📍 **Geolocation support** for finding nearby locations
- 🏪 **Sidebar with location details** and "Get Directions" links
- 🌐 **Multi-language support** (English, Portuguese)
- 📱 **Fully responsive** design
- 🎨 **Beautiful, modern UI** with smooth animations
- ⚡ **Lightweight** (~17KB total, ~11KB minified)
- 🚀 **Easy integration** - just a few lines of code
## 🚀 Quick Start
```html
<!DOCTYPE html>
<html>
<head>
<!-- Scribo Maps CSS -->
<link rel="stylesheet" href="https://unpkg.com/scribo-maps@1.0.0/dist/scribo-maps.min.css">
</head>
<body>
<div id="map-container" style="height: 500px;"></div>
<!-- Dependencies -->
<script src="https://maps.googleapis.com/maps/api/js?key=YOUR_GOOGLE_MAPS_KEY&libraries=places"></script>
<script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>
<!-- Scribo Maps JS -->
<script src="https://unpkg.com/scribo-maps@1.0.0/dist/scribo-maps.min.js"></script>
<!-- Initialize -->
<script>
new ScriboMap('map-container', {
locale: 'en-US', // or 'pt-BR'
locations: [
{
name: "Store Location",
address: "123 Main St, City",
lat: 40.7128,
lng: -74.0060,
image: "https://example.com/store-image.jpg"
}
]
});
</script>
</body>
</html>
```
## 📖 API Reference
### Constructor
```javascript
new ScriboMap(elementId, config)
```
#### Parameters
- **elementId** `string` - ID of the HTML element to render the map
- **config** `object` - Configuration object
#### Configuration Object
```javascript
{
locale: 'en-US', // 'en-US' or 'pt-BR'
locations: [ // Array of location objects
{
name: 'Store Name', // Required: Display name
address: 'Full Address', // Optional: Full address string
lat: 40.7128, // Required: Latitude
lng: -74.0060, // Required: Longitude
image: 'image-url.jpg' // Optional: Store image URL
}
]
}
```
### Methods
```javascript
const map = new ScriboMap('container', config);
// Change language dynamically
map.setLocale('pt-BR');
// Get currently displayed locations
const visibleLocations = map.getCurrentlyDisplayedLocations();
```
## 🌐 Internationalization
Scribo Maps supports multiple languages:
### English (en-US)
```javascript
new ScriboMap('map', {
locale: 'en-US',
locations: [...]
});
```
### Portuguese (pt-BR)
```javascript
new ScriboMap('map', {
locale: 'pt-BR',
locations: [...]
});
```
## 🎨 Customization
### Custom Styling
Override CSS variables to match your brand:
```css
:root {
--scribo-primary-color: #your-brand-color;
--scribo-border-radius: 12px;
--scribo-sidebar-width: 380px;
}
```
### Responsive Design
The widget automatically adapts to different screen sizes:
- **Desktop**: Full sidebar + map view
- **Mobile**: Optimized sidebar width and spacing
## 📦 File Structure
When you install or use via CDN, you get:
```
scribo-maps/
├── dist/
│ ├── scribo-maps.js # Source (16KB)
│ ├── scribo-maps.min.js # Minified (11KB)
│ ├── scribo-maps.css # Source styles (8KB)
│ ├── scribo-maps.min.css # Minified styles (6KB)
│ └── scribo-maps.min.js.map # Source map
```
## 🔧 Dependencies
### Required
- **Google Maps JavaScript API** with Places library
- **MarkerClusterer** for marker clustering
### Peer Dependencies
- `@googlemaps/markerclusterer: ^2.0.0`
## 💡 Usage Examples
### Basic Store Locator
```javascript
new ScriboMap('store-locator', {
locale: 'en-US',
locations: [
{
name: "Downtown Store",
address: "123 Main St, Downtown",
lat: 40.7128,
lng: -74.0060,
image: "https://example.com/store1.jpg"
},
{
name: "Mall Location",
address: "456 Shopping Center Dr",
lat: 40.7589,
lng: -73.9851,
image: "https://example.com/store2.jpg"
}
]
});
```
### Restaurant Locator
```javascript
new ScriboMap('restaurant-finder', {
locale: 'pt-BR',
locations: [
{
name: "Restaurante Central",
address: "Rua Principal, 100 - Centro",
lat: -23.5505,
lng: -46.6333,
image: "https://example.com/restaurant.jpg"
}
]
});
```
### Service Locations
```javascript
new ScriboMap('service-locations', {
locale: 'en-US',
locations: [
{
name: "Service Center North",
address: "789 Service Ave, North District",
lat: 41.8781,
lng: -87.6298,
image: "" // Will use placeholder icon
}
]
});
```
## 🚀 CDN Options
- **unpkg**: `https://unpkg.com/scribo-maps@1.0.0/dist/`
- **jsDelivr**: `https://cdn.jsdelivr.net/npm/scribo-maps@1.0.0/dist/`
## 📦 How to Deploy Your Own Version
If you want to create your own version or contribute to Scribo Maps, here's how to set up and deploy:
### Prerequisites
- Node.js 16+ and npm
- NPM account (create at [npmjs.com](https://npmjs.com))
- Google Maps API key for testing
### Development Setup
1. **Clone and setup:**
```bash
git clone https://github.com/scribo-dev/scribo-maps.git
cd scribo-maps
npm install
```
2. **Build the project:**
```bash
npm run build
```
This creates minified files in the `dist/` folder:
- `scribo-maps.min.js` (11KB)
- `scribo-maps.min.css` (6KB)
- Source maps for debugging
3. **Test locally:**
```bash
# Open index.html in your browser
# Or serve with a local server
npx serve .
```
### Publishing to NPM
1. **Login to NPM:**
```bash
npm login
```
2. **Update version (if needed):**
```bash
npm version patch # 1.0.0 → 1.0.1
npm version minor # 1.0.0 → 1.1.0
npm version major # 1.0.0 → 2.0.0
```
3. **Publish:**
```bash
npm publish
```
The `prepublishOnly` script automatically builds fresh minified files before publishing.
### What Gets Published
Your NPM package will include:
- `dist/scribo-maps.js` - Source JavaScript (16KB)
- `dist/scribo-maps.min.js` - Minified JavaScript (11KB)
- `dist/scribo-maps.css` - Source CSS (8KB)
- `dist/scribo-maps.min.css` - Minified CSS (6KB)
- `dist/scribo-maps.min.js.map` - Source map for debugging
- `package.json` - Package metadata
### CDN Availability
Once published, your package is automatically available on:
- **unpkg**: `https://unpkg.com/your-package@version/dist/`
- **jsDelivr**: `https://cdn.jsdelivr.net/npm/your-package@version/dist/`
Files are available within minutes of publishing!
### Build Scripts
```bash
npm run clean # Remove dist/ folder
npm run build:js # Minify JavaScript with source maps
npm run build:css # Minify CSS
npm run build # Complete build process
```
### Package Structure
```
scribo-maps/
├── 📁 Source files (committed to git)
│ ├── scribo-maps.js ← Main JavaScript
│ ├── scribo-maps.css ← Main stylesheet
│ ├── index.html ← Demo page
│ └── package.json ← NPM configuration
│
├── 📁 dist/ (ignored by git, published to NPM)
│ ├── scribo-maps.js ← Source copy
│ ├── scribo-maps.css ← Source copy
│ ├── scribo-maps.min.js ← Minified JS
│ ├── scribo-maps.min.css ← Minified CSS
│ └── *.js.map ← Source maps
│
└── 📁 node_modules/ (ignored)
```
### Best Practices
- ✅ **Test before publishing** with `npm run build`
- ✅ **Use semantic versioning** for updates
- ✅ **Update README** for major changes
- ✅ **Keep source files clean** (dist/ is auto-generated)
- ✅ **Test on multiple CDNs** after publishing
## 🌟 Browser Support
- ✅ Chrome 60+
- ✅ Firefox 55+
- ✅ Safari 12+
- ✅ Edge 79+
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
## 📱 Mobile Features
- Touch-friendly interface
- Responsive sidebar
- Optimized marker clustering
- Smooth pan and zoom
- Native "Get Directions" integration
## 🔐 Security
- No API keys hardcoded
- Client provides their own Google Maps API key
- Content Security Policy friendly
- XSS protection built-in
## ⚡ Performance
- **Lazy loading** of map tiles
- **Marker clustering** for large datasets
- **Debounced search** to reduce API calls
- **Minified assets** for fast loading
- **CDN delivery** for global performance
## 🐛 Troubleshooting
### Common Issues
**Map not showing:**
- Check that your Google Maps API key is valid
- Ensure the Places library is included: `&libraries=places`
- Verify the container element exists
**Locations not appearing:**
- Check that lat/lng coordinates are valid numbers
- Ensure locations array is properly formatted
- Verify API key has proper permissions
**Styling issues:**
- Make sure CSS file is loaded before JS
- Check for CSS conflicts with your site's styles
- Verify container has a defined height
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🤝 Contributing
1. Fork the repository
2. Create your 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
- 🐛 **Issues**: [GitHub Issues](https://github.com/scribo-dev/scribo-maps/issues)
- 📖 **Documentation**: [GitHub Wiki](https://github.com/scribo-dev/scribo-maps/wiki)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/scribo-dev/scribo-maps/discussions)
## 🏆 Showcase
*Using Scribo Maps in your project? Let us know and we'll feature it here!*
---
**Made with ❤️ by the Scribo team**
*Scribo Maps - Making location-based applications simple and beautiful.*