scribo-maps

v1.0.7

Published

10 months ago

Embeddable map widget for store locators

Downloads

0High
0Medium
0Low

relferreira-scribo

maps store-locator google-maps widget embeddable

🗺️ 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.

✨ 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

<!DOCTYPE html>
<html>
<head>
    <!-- Scribo Maps CSS -->
    <link rel="stylesheet" href="https://unpkg.com/[email protected]/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/[email protected]/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

new ScriboMap(elementId, config)

Parameters

elementId string - ID of the HTML element to render the map
config object - Configuration object

Configuration Object

{
    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

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)

new ScriboMap('map', {
    locale: 'en-US',
    locations: [...]
});

Portuguese (pt-BR)

new ScriboMap('map', {
    locale: 'pt-BR',
    locations: [...]
});

🎨 Customization

Custom Styling

Override CSS variables to match your brand:

: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

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

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

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/[email protected]/dist/
jsDelivr: https://cdn.jsdelivr.net/npm/[email protected]/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)
Google Maps API key for testing

Development Setup

Clone and setup:

git clone https://github.com/scribo-dev/scribo-maps.git
cd scribo-maps
npm install

Build the project:

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

Test locally:

# Open index.html in your browser
# Or serve with a local server
npx serve .

Publishing to NPM

Login to NPM:

npm login

Update version (if needed):

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

Publish:

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

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 file for details.

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📞 Support

🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki
💬 Discussions: GitHub 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.