npm - map-gl-style-switcher - Versions diffs - 0.7.5 → 0.9.1 - Mend

map-gl-style-switcher 0.7.5 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -13,14 +13,17 @@ A TypeScript control for switching Mapbox GL / MapLibre GL map styles. Easily ad
 - `StyleSwitcherControl` - Direct IControl implementation for Mapbox/MapLibre GL
 - `MapGLStyleSwitcher` - React component for react-map-gl integration
+  _Live demo of the style switcher control in action_
 **<a href="https://map-gl-style-switcher.netlify.app/" target="_blank">🌐 Live Demo</a>**
-## Demo
+## Animated Demo
 ![Demo GIF](./images/demo.gif)
-_Live demo of the style switcher control in action_
+## Available Styles
+![Available Styles](./images/styles.png)
 ## Features
@@ -33,7 +36,7 @@ _Live demo of the style switcher control in action_
 - RTL text support for Arabic scripts
 - Configurable display options (show/hide labels and images)
 - Callbacks for before/after style change
-- Fully customizable CSS classes
+- Fully customizable CSS classe's
 - TypeScript support
 - Accessibility features (ARIA labels, keyboard navigation)
 - Comprehensive test coverage
@@ -51,166 +54,49 @@ yarn add map-gl-style-switcher
 pnpm add map-gl-style-switcher
 ```
-## CDN Usage
-For quick prototyping or when you don't want to use a build system, you can include the package directly from a CDN:
-### unpkg CDN
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <!-- MapLibre GL CSS -->
-  <link href="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.css" rel="stylesheet" />
-  <!-- Style Switcher CSS -->
-  <link rel="stylesheet" href="https://unpkg.com/map-gl-style-switcher@latest/dist/map-gl-style-switcher.css">
-</head>
-<body>
-  <div id="map" style="width: 100%; height: 100vh;"></div>
-  <!-- MapLibre GL JS -->
-  <script src="https://unpkg.com/maplibre-gl@4/dist/maplibre-gl.js"></script>
-  <!-- Style Switcher UMD -->
-  <script src="https://unpkg.com/map-gl-style-switcher@latest/dist/index.umd.js"></script>
-  <script>
-    // StyleSwitcherControl is available globally as MapGLStyleSwitcher.StyleSwitcherControl
-    const { StyleSwitcherControl } = MapGLStyleSwitcher;
-    const styles = [
-      {
-        id: 'voyager',
-        name: 'Voyager',
-        image: 'https://unpkg.com/map-gl-style-switcher@latest/public/voyager.png',
-        styleUrl: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
-        description: 'Voyager style from Carto',
-      },
-      {
-        id: 'positron',
-        name: 'Positron',
-        image: 'https://unpkg.com/map-gl-style-switcher@latest/public/positron.png',
-        styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
-        description: 'Positron style from Carto',
-      }
-    ];
-    const map = new maplibregl.Map({
-      container: 'map',
-      style: styles[0].styleUrl,
-      center: [0, 0],
-      zoom: 2
-    });
-    const styleSwitcher = new StyleSwitcherControl({
-      styles: styles,
-      theme: 'auto',
-      activeStyleId: styles[0].id,
-      onAfterStyleChange: (from, to) => {
-        map.setStyle(to.styleUrl);
-      }
-    });
-    map.addControl(styleSwitcher, 'bottom-left');
-  </script>
-</body>
-</html>
-```
+### Basic Map Instance
-### jsDelivr CDN
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <!-- MapLibre GL CSS -->
-  <link href="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.css" rel="stylesheet" />
-  <!-- Style Switcher CSS -->
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/map-gl-style-switcher@latest/dist/map-gl-style-switcher.css">
-</head>
-<body>
-  <div id="map" style="width: 100%; height: 100vh;"></div>
-  <!-- MapLibre GL JS -->
-  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.js"></script>
-  <!-- Style Switcher UMD -->
-  <script src="https://cdn.jsdelivr.net/npm/map-gl-style-switcher@latest/dist/index.umd.js"></script>
-  <script>
-    // Same JavaScript code as above
-    const { StyleSwitcherControl } = MapGLStyleSwitcher;
-    // ... rest of the code
-  </script>
-</body>
-</html>
-```
+For React applications where you manage the map instance yourself (e.g., with `useEffect`), use the `useStyleSwitcher` hook:
-### ES Modules from CDN
-For modern browsers that support ES modules:
-```html
-<script type="module">
-  import { StyleSwitcherControl } from 'https://unpkg.com/map-gl-style-switcher@latest/dist/index.js';
-  // Your code here
-  const styleSwitcher = new StyleSwitcherControl({
-    styles: styles,
-    theme: 'auto'
-  });
-</script>
-```
-### Specific Version
-To use a specific version instead of `@latest`:
-```html
-<!-- Replace @latest with specific version, e.g., @0.7.2 -->
-<link rel="stylesheet" href="https://unpkg.com/map-gl-style-switcher@0.7.2/dist/map-gl-style-switcher.css">
-<script src="https://unpkg.com/map-gl-style-switcher@0.7.2/dist/index.umd.js"></script>
-```
-## Usage
-### Basic MapLibre GL Integration
-```ts
-import maplibregl from 'maplibre-gl';
-import { StyleSwitcherControl } from 'map-gl-style-switcher';
+```tsx
+import React, { useEffect, useRef } from 'react';
+import * as maplibregl from 'maplibre-gl';
+import { StyleSwitcherControl, type StyleItem } from 'map-gl-style-switcher';
+// Custom hook
+// import { useStyleSwitcher } from 'map-gl-style-switcher/react';
+import 'maplibre-gl/dist/maplibre-gl.css';
 import 'map-gl-style-switcher/dist/map-gl-style-switcher.css';
-// Define styles
-const styles = [
+const mapStyles: StyleItem[] = [
   {
     id: 'voyager',
     name: 'Voyager',
-    image: './voyager.png',
+    image:
+      'https://raw.githubusercontent.com/muimsd/map-gl-style-switcher/refs/heads/main/public/voyager.png',
     styleUrl: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
     description: 'Voyager style from Carto',
   },
   {
     id: 'positron',
     name: 'Positron',
-    image: './positron.png',
+    image:
+      'https://raw.githubusercontent.com/muimsd/map-gl-style-switcher/refs/heads/main/public/positron.png',
     styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
     description: 'Positron style from Carto',
   },
   {
     id: 'dark-matter',
     name: 'Dark Matter',
-    image: './dark.png',
+    image:
+      'https://raw.githubusercontent.com/muimsd/map-gl-style-switcher/refs/heads/main/public/dark.png',
     styleUrl: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
     description: 'Dark style from Carto',
   },
   {
     id: 'arcgis-hybrid',
     name: 'ArcGIS Hybrid',
-    image: './arcgis-hybrid.png',
+    image:
+      'https://raw.githubusercontent.com/muimsd/map-gl-style-switcher/refs/heads/main/public/arcgis-hybrid.png',
     styleUrl:
       'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/arcgis_hybrid.json',
     description: 'Hybrid Satellite style from ESRI',
@@ -218,301 +104,88 @@ const styles = [
   {
     id: 'osm',
     name: 'OSM',
-    image: './osm.png',
+    image:
+      'https://raw.githubusercontent.com/muimsd/map-gl-style-switcher/refs/heads/main/public/osm.png',
     styleUrl:
       'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/openStreetMap.json',
     description: 'OSM style',
   },
 ];
-const defaultStyle = styles[0];
-// Create map
-const map = new maplibregl.Map({
-  container: 'map',
-  style: defaultStyle.styleUrl,
-  center: [0, 0],
-  zoom: 2,
-});
-// Add style switcher control
-const styleSwitcher = new StyleSwitcherControl({
-  styles: styles,
-  theme: 'light', // 'light', 'dark', or 'auto'
-  showLabels: true,
-  showImages: true,
-  activeStyleId: defaultStyle.id,
-  onBeforeStyleChange: (from, to) => {
-    console.log(`Switching from ${from.name} to ${to.name}`);
-  },
-  onAfterStyleChange: (from, to) => {
-    map.setStyle(to.styleUrl);
-  },
-});
-map.addControl(styleSwitcher, 'bottom-left');
-```
-### React Integration with react-map-gl
-For React applications using `react-map-gl`, This package provides a ready-to-use `MapGLStyleSwitcher` component:
+export default function App() {
+  const mapContainer = useRef<HTMLDivElement | null>(null)
-```tsx
-import React, { useState } from 'react';
-import { Map } from 'react-map-gl/maplibre';
-import { MapGLStyleSwitcher } from 'map-gl-style-switcher';
-import 'map-gl-style-switcher/dist/map-gl-style-switcher.css';
+  useEffect(() => {
+    if (!mapContainer.current) {
+      console.error('Map container not found!');
+      return;
+    }
+    const currentStyle = mapStyles[0];
+    const map = new maplibregl.Map({
+      container: mapContainer.current,
+      // Use a simple, reliable style first
+      style: currentStyle.styleUrl,
+      // Center on Dubai, UAE
+      center: [55.2708, 25.2048],
+      zoom: 10,
+    });
-const styles = [
-  {
-    id: 'voyager',
-    name: 'Voyager',
-    image: './voyager.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
-    description: 'Voyager style from Carto',
-  },
-  {
-    id: 'positron',
-    name: 'Positron',
-    image: './positron.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
-    description: 'Positron style from Carto',
-  },
-  {
-    id: 'dark-matter',
-    name: 'Dark Matter',
-    image: './dark.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
-    description: 'Dark style from Carto',
-  },
-  {
-    id: 'arcgis-hybrid',
-    name: 'ArcGIS Hybrid',
-    image: './arcgis-hybrid.png',
-    styleUrl:
-      'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/arcgis_hybrid.json',
-    description: 'Hybrid Satellite style from ESRI',
-  },
-  {
-    id: 'osm',
-    name: 'OSM',
-    image: './osm.png',
-    styleUrl:
-      'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/openStreetMap.json',
-    description: 'OSM style',
-  },
-];
+    // Add style switcher control
+    const styleSwitcher = new StyleSwitcherControl({
+      styles: mapStyles,
+      theme: 'auto',
+      showLabels: true,
+      showImages: true,
+      activeStyleId: currentStyle.id,
+      onBeforeStyleChange: (from, to) => {
+        console.log('Changing style from', from.name, 'to', to.name);
+      },
+      onAfterStyleChange: (_from, to) => {
+        map.setStyle(to.styleUrl);
+        console.log('Style changed to', to.name);
+      },
+    });
+    map.addControl(styleSwitcher, 'bottom-left');
-export const MapComponent = () => {
-  const [mapStyle, setMapStyle] = useState(styles[0].styleUrl);
+    return () => {
+      map.remove();
+    };
+  }, []); // Empty dependency array
+  // Add style switcher control to the map
+  // useStyleSwitcher(map.current, {
+  //   styles,
+  //   theme: 'auto',
+  //   position: 'top-right',
+  //   onAfterStyleChange: (from, to) => {
+  //     if (map.current) {
+  //       map.current.setStyle(to.styleUrl);
+  //     }
+  //   },
+  // });
   return (
-    <Map
-      mapLib={import('maplibre-gl')}
-      initialViewState={{
-        longitude: 0,
-        latitude: 0,
-        zoom: 2,
+    <div
+      ref={mapContainer}
+      style={{
+        width: '100%',
+        height: '500px',
       }}
-      style={{ width: '100%', height: '100vh' }}
-      mapStyle={mapStyle}
-    >
-      <MapGLStyleSwitcher
-        styles={styles}
-        activeStyleId={styles[0].id}
-        theme="auto"
-        showLabels={true}
-        showImages={true}
-        onStyleChange={setMapStyle}
-        position="bottom-left"
-      />
-    </Map>
+    />
   );
-};
-```
-**Installation for React:**
-```sh
-npm install react-map-gl maplibre-gl map-gl-style-switcher
-```
-#### MapGLStyleSwitcher Props
-```tsx
-interface MapGLStyleSwitcherProps {
-  styles: StyleItem[]; // Array of map styles (required)
-  activeStyleId?: string; // Currently active style ID
-  theme?: 'light' | 'dark' | 'auto'; // UI theme (default: 'light')
-  showLabels?: boolean; // Show style names (default: true)
-  showImages?: boolean; // Show style thumbnails (default: true)
-  position?:
-    | 'top-left'
-    | 'top-right' // Control position (default: 'bottom-left')
-    | 'bottom-left'
-    | 'bottom-right';
-  animationDuration?: number; // Animation duration in ms (default: 200)
-  maxHeight?: number; // Max height of expanded list (default: 300)
-  rtl?: boolean; // Enable RTL layout (default: false)
-  classNames?: Partial<{
-    // Custom CSS classes
-    container: string;
-    list: string;
-    item: string;
-    itemSelected: string;
-    itemHideLabel: string;
-    dark: string;
-    light: string;
-  }>;
-  onBeforeStyleChange?: (from: StyleItem, to: StyleItem) => void; // Callback before style change
-  onAfterStyleChange?: (from: StyleItem, to: StyleItem) => void; // Callback after style change
-  onStyleChange?: (styleUrl: string) => void; // Simplified callback for style URL
 }
-```
-#### Advanced React Usage
-For more complex scenarios, you can use both callbacks:
-```tsx
-const MapComponent = () => {
-  const [mapStyle, setMapStyle] = useState(styles[0].styleUrl);
-  const [loading, setLoading] = useState(false);
-  const handleBeforeStyleChange = (from: StyleItem, to: StyleItem) => {
-    console.log(`Switching from ${from.name} to ${to.name}`);
-    setLoading(true);
-  };
-  const handleAfterStyleChange = (from: StyleItem, to: StyleItem) => {
-    console.log(`Style changed to ${to.name}`);
-    setLoading(false);
-  };
-  const handleStyleChange = (styleUrl: string) => {
-    setMapStyle(styleUrl);
-  };
-  return (
-    <Map mapStyle={mapStyle} /* ...other props */>
-      <MapGLStyleSwitcher
-        styles={styles}
-        activeStyleId="voyager"
-        theme="auto"
-        onBeforeStyleChange={handleBeforeStyleChange}
-        onAfterStyleChange={handleAfterStyleChange}
-        onStyleChange={handleStyleChange}
-        position="bottom-left"
-      />
-      {loading && <div className="loading-indicator">Switching style...</div>}
-    </Map>
-  );
-};
 ```
 ## Examples
-### React + Vite + TypeScript Example
-A complete working example is available in the `examples/react-map-gl` directory:
-```bash
-cd examples/react-map-gl
-npm install
-npm run dev
-```
-This example demonstrates:
-- React 19 with TypeScript and Vite 7
-- MapLibre GL integration with react-map-gl
-- MapGLStyleSwitcher component usage
-- Multiple basemap styles with thumbnails
-- Responsive design with auto theme detection
-- Style switching with smooth transitions
-[View the complete example →](examples/react-map-gl/)
-### Vanilla JavaScript Example
-The main demo at the root level demonstrates vanilla JavaScript usage:
-```bash
-npm install
-npm run dev
-```
-This example shows:
-- Pure TypeScript/JavaScript implementation
-- MapLibre GL integration
-- StyleSwitcherControl direct usage
-- Multiple themes and configuration options
-## Available Styles
-![Available Styles](./images/styles.png)
-The style switcher supports various map styles. Here are some popular options you can use:
-### Carto Basemaps
-- **Voyager** - A balanced, colorful style perfect for data visualization and general mapping applications
-- **Positron** - A clean, minimal light basemap ideal for overlaying data with maximum contrast
-- **Dark Matter** - A dark theme basemap excellent for creating striking data visualizations and night mode interfaces
+### React Map GL Example
-### Satellite & Hybrid
+[View the maplibre example →](examples/maplibre/)
-- **ArcGIS Hybrid** - Combines satellite imagery with street labels, perfect for geographic context and navigation
-- **Satellite** - High-resolution satellite imagery for detailed geographic analysis
-### OpenStreetMap
-- **OSM (OpenStreetMap)** - Community-driven open-source mapping with detailed street-level information
-### Example Styles Configuration
-```ts
-const styles = [
-  {
-    id: 'voyager',
-    name: 'Voyager',
-    image: './voyager.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
-    description: 'Voyager style from Carto',
-  },
-  {
-    id: 'positron',
-    name: 'Positron',
-    image: './positron.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
-    description: 'Positron style from Carto',
-  },
-  {
-    id: 'dark-matter',
-    name: 'Dark Matter',
-    image: './dark.png',
-    styleUrl: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
-    description: 'Dark style from Carto',
-  },
-  {
-    id: 'arcgis-hybrid',
-    name: 'ArcGIS Hybrid',
-    image: './arcgis-hybrid.png',
-    styleUrl:
-      'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/arcgis_hybrid.json',
-    description: 'Hybrid Satellite style from ESRI',
-  },
-  {
-    id: 'osm',
-    name: 'OSM',
-    image: './osm.png',
-    styleUrl:
-      'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/openStreetMap.json',
-    description: 'OSM style',
-  },
-];
-```
+### React Map GL Example
-> **Note**: The `description` property is optional and will be shown as a tooltip when users hover over a style option.
+[View the react-map-gl example →](examples/react-map-gl/)
 ## Configuration Options
@@ -587,100 +260,6 @@ const styleSwitcher = new StyleSwitcherControl({
 See the default class names in the `StyleSwitcherControl` source for all available keys.
-## File Structure
-```
-map-gl-style-switcher/
-├── src/
-│   ├── components/
-│   │   ├── StyleSwitcherControl.ts    # Main IControl implementation
-│   │   └── MapGLStyleSwitcher.tsx     # React component for react-map-gl
-│   ├── styles/
-│   │   └── style-switcher.css         # Control styles (themes, RTL support)
-│   ├── types/
-│   │   ├── index.ts                   # TypeScript type definitions
-│   │   └── css.d.ts                   # CSS module declarations
-│   ├── tests/
-│   │   ├── StyleSwitcherControl.test.ts # Core control test suite
-│   │   ├── MapGLStyleSwitcher.test.tsx  # React component test suite
-│   │   └── test-setup.ts              # Jest test setup
-│   ├── demo/
-│   │   ├── main.tsx                   # Demo entry point
-│   │   ├── App.tsx                    # Demo component
-│   │   └── index.css                  # Demo-specific styles
-│   └── index.ts                       # Package entry point
-├── examples/
-│   └── react-map-gl/                  # Complete React example
-│       ├── src/
-│       │   ├── App.tsx                # Example React application
-│       │   └── main.tsx               # React entry point
-│       ├── package.json               # Example dependencies
-│       └── vite.config.ts             # Vite configuration
-├── dist/                              # Built package output
-│   ├── index.js                       # ES Module
-│   ├── index.umd.js                   # UMD Module
-│   ├── index.d.ts                     # TypeScript declarations
-│   └── map-gl-style-switcher.css       # Bundled CSS
-├── package.json                       # Package configuration
-├── rollup.config.js                   # Production build configuration
-├── vite.config.ts                     # Development build configuration
-├── jest.config.js                     # Test configuration
-├── tsconfig.json                      # TypeScript configuration
-└── README.md                          # Documentation
-```
-## Development
-This project uses npm for dependency management.
-### Prerequisites
-```sh
-# Ensure you have Node.js 16+ and npm 8+ installed
-node --version
-npm --version
-```
-### Quick Start
-```sh
-# Install dependencies
-npm install
-# Start development server
-npm run dev
-# Build for production
-npm run build
-# Run tests
-npm test
-# Lint and format code
-npm run lint
-npm run format
-# Validate before publishing
-npm run validate
-```
-## Build for npm
-The project uses Rollup for optimized production builds, generating:
-- `dist/index.js` - ES module format
-- `dist/index.umd.js` - UMD format for browser usage
-- `dist/index.d.ts` - TypeScript declarations
-- `dist/map-gl-style-switcher.css` - Minified CSS styles
-```sh
-# Standard build
-npm run build
-# Production build with full validation
-npm run build:prod
-```
 ## Contributing
 We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
@@ -719,23 +298,6 @@ We welcome contributions! Please feel free to submit a Pull Request. For major c
 6. **Submit a pull request**
-### Available Scripts
-- `npm run dev` - Start development server with hot reload
-- `npm run build` - Build library with Rollup (ES modules, UMD, TypeScript declarations, and CSS)
-- `npm run build:prod` - Production build with validation (type-check, lint, and build)
-- `npm run build:watch` - Build in watch mode with Rollup
-- `npm test` - Run tests
-- `npm run test:watch` - Run tests in watch mode
-- `npm run test:coverage` - Run tests with coverage
-- `npm run lint` - Lint code
-- `npm run lint:fix` - Lint and auto-fix issues
-- `npm run format` - Format code with Prettier
-- `npm run format:check` - Check code formatting
-- `npm run validate` - Run all validation checks
-- `npm run type-check` - Type check TypeScript
-- `npm run clean` - Clean build artifacts
 ### Guidelines
 - Use npm for dependency management