npm - map-gl-style-switcher - Versions diffs - 0.7.2 → 0.9.0 - Mend

map-gl-style-switcher 0.7.2 → 0.9.0

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 (15) hide show

package/README.md +204 -217
package/dist/index-CsaOV7jZ.d.ts +52 -0
package/dist/index.d.ts +1 -117
package/dist/index.js +1 -53
package/dist/index.js.map +1 -1
package/dist/index.umd.js +4 -55
package/dist/index.umd.js.map +1 -1
package/dist/map-gl-style-switcher.css +195 -1
package/dist/react-map-gl.d.ts +68 -0
package/dist/react-map-gl.js +55 -0
package/dist/react-map-gl.js.map +1 -0
package/dist/react.d.ts +52 -0
package/dist/react.js +67 -0
package/dist/react.js.map +1 -0
package/package.json +20 -10

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
@@ -51,7 +54,131 @@ yarn add map-gl-style-switcher
 pnpm add map-gl-style-switcher
 ```
-## Usage
+## 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 and jsDelivr CDN
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <!-- jsDelivr CDN -->
+    <!-- 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"
+    /> -->
+    <!-- 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>
+    <!-- jsDelivr CDN -->
+    <!-- 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> -->
+    <!-- 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://github.com/muimsd/map-gl-style-switcher/tree/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: 'https://github.com/muimsd/map-gl-style-switcher/tree/main/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>
+```
+### 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>
+```
+### Entry Point Guide
+#### For Vanilla JavaScript/TypeScript Users
+```ts
+import { StyleSwitcherControl } from 'map-gl-style-switcher';
+// No React dependencies required
+```
+#### For React with Custom Map Instance
+```tsx
+import { useStyleSwitcher } from 'map-gl-style-switcher/react';
+// Pure React hook - works with any map instance (MapLibre, Mapbox, etc.)
+// Only requires: react (no react-map-gl dependency)
+```
+#### For React with react-map-gl
+```tsx
+import { MapGLStyleSwitcher } from 'map-gl-style-switcher/react-map-gl';
+// React component using react-map-gl's useControl
+// Requires: react + react-map-gl
+```
 ### Basic MapLibre GL Integration
@@ -65,28 +192,28 @@ const styles = [
   {
     id: 'voyager',
     name: 'Voyager',
-    image: './voyager.png',
+    image: 'https://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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',
@@ -94,7 +221,7 @@ const styles = [
   {
     id: 'osm',
     name: 'OSM',
-    image: './osm.png',
+    image: 'https://github.com/muimsd/map-gl-style-switcher/tree/main/public/osm.png',
     styleUrl:
       'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/openStreetMap.json',
     description: 'OSM style',
@@ -127,42 +254,102 @@ const styleSwitcher = new StyleSwitcherControl({
 map.addControl(styleSwitcher, 'bottom-left');
 ```
+### React Hook for Custom Map Instances
+For React applications where you manage the map instance yourself (e.g., with `useEffect`), use the `useStyleSwitcher` hook:
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { useStyleSwitcher } from 'map-gl-style-switcher/react';
+import maplibregl from 'maplibre-gl';
+import 'map-gl-style-switcher/dist/map-gl-style-switcher.css';
+const styles = [
+  {
+    id: 'voyager',
+    name: 'Voyager',
+    image: 'https://github.com/muimsd/map-gl-style-switcher/tree/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: 'https://github.com/muimsd/map-gl-style-switcher/tree/main/public/positron.png',
+    styleUrl: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+    description: 'Positron style from Carto',
+  },
+];
+function MyMapComponent() {
+  const mapContainer = useRef<HTMLDivElement>(null);
+  const map = useRef<maplibregl.Map | null>(null);
+  useEffect(() => {
+    if (!mapContainer.current) return;
+    map.current = new maplibregl.Map({
+      container: mapContainer.current,
+      style: styles[0].styleUrl,
+      center: [0, 0],
+      zoom: 2,
+    });
+    return () => map.current?.remove();
+  }, []);
+  // 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 <div ref={mapContainer} style={{ width: '100%', height: '400px' }} />;
+}
+```
 ### React Integration with react-map-gl
-For React applications using `react-map-gl`, This package provides a ready-to-use `MapGLStyleSwitcher` component:
+For React applications using `react-map-gl`, this package provides a ready-to-use `MapGLStyleSwitcher` component:
 ```tsx
 import React, { useState } from 'react';
 import { Map } from 'react-map-gl/maplibre';
-import { MapGLStyleSwitcher } from 'map-gl-style-switcher';
+import { MapGLStyleSwitcher } from 'map-gl-style-switcher/react-map-gl';
 import 'map-gl-style-switcher/dist/map-gl-style-switcher.css';
 const styles = [
   {
     id: 'voyager',
     name: 'Voyager',
-    image: './voyager.png',
+    image: 'https://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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://github.com/muimsd/map-gl-style-switcher/tree/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',
@@ -170,7 +357,7 @@ const styles = [
   {
     id: 'osm',
     name: 'OSM',
-    image: './osm.png',
+    image: 'https://github.com/muimsd/map-gl-style-switcher/tree/main/public/osm.png',
     styleUrl:
       'https://raw.githubusercontent.com/go2garret/maps/main/src/assets/json/openStreetMap.json',
     description: 'OSM style',
@@ -205,12 +392,6 @@ export const MapComponent = () => {
 };
 ```
-**Installation for React:**
-```sh
-npm install react-map-gl maplibre-gl map-gl-style-switcher
-```
 #### MapGLStyleSwitcher Props
 ```tsx
@@ -284,6 +465,8 @@ const MapComponent = () => {
 };
 ```
+**Note:** This hook automatically handles adding/removing the control when the map or options change.
 ## Examples
 ### React + Vite + TypeScript Example
@@ -302,94 +485,9 @@ This example demonstrates:
 - 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
-### Satellite & Hybrid
-- **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',
-  },
-];
-```
-> **Note**: The `description` property is optional and will be shown as a tooltip when users hover over a style option.
 ## Configuration Options
 ```ts
@@ -463,100 +561,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.
@@ -595,23 +599,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

package/dist/index-CsaOV7jZ.d.ts ADDED Viewed

@@ -0,0 +1,52 @@
+type MapInstance = any;
+interface IControl {
+    onAdd(map: MapInstance): HTMLElement;
+    onRemove(map: MapInstance): void;
+}
+interface StyleItem {
+    id: string;
+    name: string;
+    image: string;
+    styleUrl: string;
+    description?: string;
+}
+interface StyleSwitcherControlOptions {
+    styles: StyleItem[];
+    activeStyleId?: string;
+    onBeforeStyleChange?: (from: StyleItem, to: StyleItem) => void;
+    onAfterStyleChange?: (from: StyleItem, to: StyleItem) => void;
+    showLabels?: boolean;
+    showImages?: boolean;
+    animationDuration?: number;
+    maxHeight?: number;
+    theme?: 'light' | 'dark' | 'auto';
+    classNames?: Partial<StyleSwitcherClassNames>;
+    rtl?: boolean;
+}
+interface StyleSwitcherClassNames {
+    container: string;
+    list: string;
+    item: string;
+    itemSelected: string;
+    itemHideLabel: string;
+    dark: string;
+    light: string;
+}
+declare class StyleSwitcherControl implements IControl {
+    private _container;
+    private _options;
+    private _activeStyleId;
+    private _expanded;
+    private _classNames;
+    constructor(options: StyleSwitcherControlOptions);
+    onAdd(_map: MapInstance): HTMLElement;
+    private _applyTheme;
+    onRemove(): void;
+    private _setExpanded;
+    private _handleStyleChange;
+    private _render;
+    private _createStyleItem;
+}
+export { StyleSwitcherControl as a };
+export type { IControl as I, StyleSwitcherControlOptions as S, StyleItem as b, StyleSwitcherClassNames as c };