npm - @bluehalo/ngx-leaflet - Versions diffs - 18.0.2 → 20.0.0 - Mend

@bluehalo/ngx-leaflet 18.0.2 → 20.0.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 (33) hide show

package/CHANGES.md +3 -0
package/README.md +128 -189
package/fesm2022/bluehalo-ngx-leaflet.mjs +27 -27
package/fesm2022/bluehalo-ngx-leaflet.mjs.map +1 -1
package/index.d.ts +314 -3
package/package.json +5 -7
package/esm2022/bluehalo-ngx-leaflet.mjs +0 -5
package/esm2022/lib/core/leaflet.directive.mjs +0 -330
package/esm2022/lib/core/leaflet.directive.wrapper.mjs +0 -12
package/esm2022/lib/core/leaflet.util.mjs +0 -20
package/esm2022/lib/layers/base/leaflet-baselayers.directive.mjs +0 -113
package/esm2022/lib/layers/control/leaflet-control-layers-changes.model.mjs +0 -11
package/esm2022/lib/layers/control/leaflet-control-layers-config.model.mjs +0 -7
package/esm2022/lib/layers/control/leaflet-control-layers.directive.mjs +0 -100
package/esm2022/lib/layers/control/leaflet-control-layers.wrapper.mjs +0 -58
package/esm2022/lib/layers/leaflet-layer.directive.mjs +0 -78
package/esm2022/lib/layers/leaflet-layers.directive.mjs +0 -83
package/esm2022/lib/layers/leaflet-tile-layer-definition.model.mjs +0 -53
package/esm2022/lib/leaflet.module.mjs +0 -40
package/esm2022/public-api.mjs +0 -13
package/lib/core/leaflet.directive.d.ts +0 -94
package/lib/core/leaflet.directive.wrapper.d.ts +0 -8
package/lib/core/leaflet.util.d.ts +0 -7
package/lib/layers/base/leaflet-baselayers.directive.d.ts +0 -45
package/lib/layers/control/leaflet-control-layers-changes.model.d.ts +0 -6
package/lib/layers/control/leaflet-control-layers-config.model.d.ts +0 -9
package/lib/layers/control/leaflet-control-layers.directive.d.ts +0 -35
package/lib/layers/control/leaflet-control-layers.wrapper.d.ts +0 -14
package/lib/layers/leaflet-layer.directive.d.ts +0 -30
package/lib/layers/leaflet-layers.directive.d.ts +0 -41
package/lib/layers/leaflet-tile-layer-definition.model.d.ts +0 -33
package/lib/leaflet.module.d.ts +0 -11
package/public-api.d.ts +0 -12

package/CHANGES.md CHANGED Viewed

@@ -1,5 +1,8 @@
 # Changelog
+## 19.0
+Support for Angular.io 19.
 ## 18.0
 Support for Angular.io 18.

package/README.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# @asymmetrik/ngx-leaflet
+# @bluehalo/ngx-leaflet
 [![Build Status][travis-image]][travis-url]
@@ -7,10 +7,6 @@
 > Leaflet packages for Angular.io.
 > Provides flexible and extensible components for integrating Leaflet v0.7.x and v1.x into Angular.io projects.
-> Supports Angular v18 and use in Angular-CLI based projects.
-> NOTE: This is the last version of this package that will be published under the @asymmetrik namespace.
-> This and future versions will be published under the namespace: @bluehalo
 ## Table of Contents
 - [Install](#install)
@@ -28,7 +24,7 @@
 Install the package and its peer dependencies via npm (or yarn):
 ```
 npm install leaflet
-npm install @asymmetrik/ngx-leaflet
+npm install @bluehalo/ngx-leaflet
 ```
 If you intend to use this library in a typescript project (utilizing the typings), you'll need to install the leaflet typings:
@@ -41,14 +37,16 @@ If you want to run the demo, clone the repository, perform an ```npm install```,
 Not using the latest version of Angular.io? Have a look in [CHANGES.md](/CHANGES.md) to find the right version for your project.
 ## Usage
-To use this library, there are a handful of setup steps to go through that vary based on your app environment (e.g., Webpack, ngCli, SystemJS, etc.).
+> NOTE: We've simplified the getting started instructions to be more targeted at the most recent versions of Angular.io and the use of Angular CLI.
 Generally, the steps are:
 * Install Leaflet, this library, and potentially the Leaflet typings (see above).
 * Import the Leaflet stylesheet
-* Import the Leaflet module into your Angular project
+* Import the `LeafletDirective` etc. into your Module or standalone Component
 * Create and configure a map (see docs below and/or demo)
+Alternatively, you can use the `LeafletModule` to import the module into your application.
 ### Import the Leaflet Stylesheet
 For leaflet to work, you need to have the leaflet stylesheets loaded into your application.
@@ -58,7 +56,7 @@ How you include the stylesheet will depend on your specific setup. Here are a fe
 #### Direct Import from HTML
 If you are just building a webpage and not using a bundler for your css, you'll want to directly import the css file in your HTML page.
-```html
+```angular181html
 <head>
 	...
 	<link rel="stylesheet" type="text/css" href="./node_modules/leaflet/dist/leaflet.css">
@@ -66,31 +64,6 @@ If you are just building a webpage and not using a bundler for your css, you'll
 </head>
 ```
-#### Configuring Webpack Style Loaders
-If you are using Webpack, you will need to import the css file and have a style-loader configured.
-You can use the demo included in this application as a reference.
-Generally, in ```vendor.ts```:
-```ts
-import 'leaflet/dist/leaflet.css';
-```
-And then in your webpack config file:
-```js
-{
-	...
-	"module" : {
-		loaders: [
-			...
-			{ test: /\.css$/, loaders: [ 'style-loader', 'css-loader' ] },
-			...
-		]
-	},
-	...
-}
-```
 #### Adding Styles in Angular CLI
 If you are using Angular CLI, you will need to add the Leaflet CSS file to the styles array contained in ```angular.json```
@@ -105,52 +78,71 @@ If you are using Angular CLI, you will need to add the Leaflet CSS file to the s
 }
 ```
-### Import Code Dependencies and Module
-This project is exported using UMD and it includes typings.
-So, you shouldn't have to do anything special to use it if you're building your project in Typescript.
-#### Typescript Angular.io Module Import
-Before you can use the module in your Angular.io app, you'll need to import it in your application (and potentially the module that's using it).
+#### A Note About Markers
+Leaflet marker URLs don't play well with the Angular CLI build pipeline without some special handling.
+The demo contained in this project demonstrates how to get around this problem. Here is a rough overview of the steps taken to get them working.
-For example, in your ```app.module.ts```, add:
-```js
-import { LeafletModule } from '@asymmetrik/ngx-leaflet';
-...
-imports: [
+1. Include the leaflet marker assets so they are copied intact to the build output.
+```json
+{
 	...
-	LeafletModule
-]
-...
+	"assets": [
+		{
+			"glob": "**/*",
+			"input": "public"
+		},
+		{
+			"glob": "**/*",
+			"input": "./node_modules/leaflet/dist/images",
+			"output": "assets/"
+		}
+	],
+	...
+}
+```
+1. Configure Leaflet to use the asset URLs as custom marker images.
+```typescript
+let layer = marker([ 46.879966, -121.726909 ], {
+	icon: icon({
+		...Icon.Default.prototype.options,
+		iconUrl: 'assets/marker-icon.png',
+		iconRetinaUrl: 'assets/marker-icon-2x.png',
+		shadowUrl: 'assets/marker-shadow.png'
+   })
+});
 ```
-Potentially, you'll also need to import it into the module of the component that is going to actually use the ngx-leaflet directives.
-See Angular.io docs of modules for more details (https://angular.io/guide/ngmodule). In this case, in ```my-module.module.ts```, add:
-```js
-import { LeafletModule } from '@asymmetrik/ngx-leaflet';
-...
-imports: [
-	...
-	LeafletModule
-]
-...
+### Import LeafletDirective
-```
+Before you can use the Leaflet components in your Angular.io app, you'll need to import it in your application.
+Depending on if you're using standalone mode or not, you will import it into your modules and/or components.
+```typescript
+import { LeafletDirective } from '@bluehalo/ngx-leaflet';
-#### Not Using Typescript?
-You brave soul.
-The code is exported using UMD.
-The bundles are generated as part of the build (`npm run build`) and placed into the ./dist dir.
-You should be able to import is using whatever module system/builder you're using, even if you aren't using Typescript.
+@Component({
+    imports: [
+        LeafletDirective // Import the LeafletDirective here
+        // import other directives as needed
+    ],
+})
+```
+Alternatively:
+```typescript
+import { LeafletModule } from '@bluehalo/ngx-leaflet';
+@NgModule({
+    imports: [
+        LeafletModule // Import the LeafletModule here
+    ],
+})
+```
 ### Create and Configure a Map
-Once the dependencies are installed and you have imported the ```LeafletModule```, you're ready to add a map to your page.
 To get a basic map to work, you have to:
 * Apply the ```leaflet``` attribute directive (see the example below) to an existing DOM element.
@@ -158,7 +150,7 @@ To get a basic map to work, you have to:
 * Provide an initial zoom/center and set of layers either via ```leafletOptions``` or by binding to ```leafletZoom```, ```leafletCenter```, and ```leafletLayers```.
 Template:
-```html
+```angular181html
 <div style="height: 300px;"
      leaflet
      [leafletOptions]="options">
@@ -166,7 +158,7 @@ Template:
 ```
 Example leafletOptions object:
-```js
+```typescript
 options = {
 	layers: [
 		tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' })
@@ -187,7 +179,7 @@ The ```[leafletLayersControl]``` input bindings give you the ability to add the
 The layers control lets the user toggle layers and overlays on and off.
 Template:
-```html
+```angular181html
 <div style="height: 300px;"
      leaflet
      [leafletOptions]="options"
@@ -195,17 +187,27 @@ Template:
 </div>
 ```
-Example layersControl object:
-```js
-layersControl = {
-	baseLayers: {
-		'Open Street Map': tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' }),
-		'Open Cycle Map': tileLayer('https://{s}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' })
-	},
-	overlays: {
-		'Big Circle': circle([ 46.95, -122 ], { radius: 5000 }),
-		'Big Square': polygon([[ 46.8, -121.55 ], [ 46.9, -121.55 ], [ 46.9, -121.7 ], [ 46.8, -121.7 ]])
-	}
+Component with example layersControl object:
+```typescript
+import { LeafletDirective, LeafletLayersControlDirective } from '@bluehalo/ngx-leaflet';
+@Component({
+    imports: [
+        LeafletDirective,
+        LeafletLayersControlDirective,
+    ],
+})
+export class MyComponent {
+    protected readonly layersControl = {
+        baseLayers: {
+            'Open Street Map': tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' }),
+            'Open Cycle Map': tileLayer('https://{s}.tile.opencyclemap.org/cycle/{z}/{x}/{y}.png', { maxZoom: 18, attribution: '...' })
+        },
+        overlays: {
+            'Big Circle': circle([ 46.95, -122 ], { radius: 5000 }),
+            'Big Square': polygon([[ 46.8, -121.55 ], [ 46.9, -121.55 ], [ 46.9, -121.7 ], [ 46.8, -121.7 ]])
+        }
+    }
 }
 ```
@@ -218,7 +220,7 @@ There are several different ways to add layers to the map.
 You can add layers (baselayers, markers, or custom layers) to the map without showing them in the layer control using the ```[leafletLayers]``` directive.
 Template:
-```html
+```angular181html
 <div style="height: 300px;"
      leaflet
      [leafletOptions]="options"
@@ -227,7 +229,7 @@ Template:
 ```
 Layers array:
-```js
+```typescript
 layers = [
 	circle([ 46.95, -122 ], { radius: 5000 }),
 	polygon([[ 46.8, -121.85 ], [ 46.92, -121.92 ], [ 46.87, -121.8 ]]),
@@ -236,19 +238,22 @@ layers = [
 ```
 You can also add an individual layer to the map using the ```[leafletLayer]``` directive.
-Using this approach allows you to use ```*ngFor``` and ```*ngIf``` to control whether individual layers are added to or removed from the map.
+Using this approach allows you to use ```@for``` and ```@if``` to control whether individual layers are added to or removed from the map.
 Template:
-```html
+```angular181html
 <div style="height: 300px;"
      leaflet
      [leafletOptions]="options">
-     <div *ngIf="showLayer" [leafletLayer]="layer"></div>
+    @if (showLayer) {
+        <div [leafletLayer]="layer"></div>
+    }
 </div>
 ```
 Layer:
-```js
+```typescript
 layer = circle([ 46.95, -122 ], { radius: 5000 });
 ```
@@ -287,7 +292,7 @@ This section includes more detailed documentation of the functionality of the di
 ### Advanced Map Configuration
 There are several input bindings available for configuring the map.
-```html
+```angular181html
 <div leaflet style="height: 300px;"
      [leafletOptions]="options"
      [leafletPanOptions]="panOptions"
@@ -314,7 +319,7 @@ Input binding for FitBounds options (see [Leaflet's](https://leafletjs.com/Slava
 ### Dynamically changing zoom level, center, fitBounds, etc.
-```html
+```angular181html
 <div leaflet style="height: 300px;"
      [leafletOptions]="options"
      [(leafletZoom)]="zoom"
@@ -355,7 +360,7 @@ If you plan to show more than just baselayers, you should use the more advanced
 For an example of the basic map setup, you should check out the *Simple Base Layers* demo.
-```html
+```angular181html
 <div leaflet style="height: 300px;"
      [leafletOptions]="options"
      [leafletBaseLayers]="baseLayers"
@@ -366,7 +371,7 @@ For an example of the basic map setup, you should check out the *Simple Base Lay
 #### [leafletBaseLayers]: Control.LayersObject
 Input bind an ```Control.LayersObject``` to be synced to the map.
-```js
+```typescript
 baseLayers: {
 	'layer1': Layer,
 	'layer2': Layer
@@ -402,7 +407,7 @@ And, use ```[leafletLayersControl]``` to allow users to optionally turn layers/o
 For an example of using the layers controls, you should check out the *Layers and Layer Controls* demo.
-```html
+```angular181html
 <div leaflet style="height: 300px;"
      [leafletOptions]="options"
      [leafletLayers]="layers"
@@ -423,7 +428,7 @@ As a result of how the map is synced, the order of layers is not guaranteed to b
 #### [leafletLayersControl]: Control.Layers
 Input bind a Control.Layers specification. The object contains properties for each of the two constructor arguments for the Control.Layers constructor.
-```js
+```typescript
 layersControl: {
 	baseLayers: {
 		'layerName': Layer
@@ -439,16 +444,20 @@ Input binding for Control.Layers options (see [Leaflet's](https://leafletjs.com/
 These options are passed into the constructor on creation.
-### Advanced Layer Management: Individual Layers and *ngFor / *ngIf
+### Advanced Layer Management: Individual Layers and @for / @if
 The ```[leafletLayer]``` input bindings gives you the ability to add a single layer to the map.
 While this may seem limiting, you can nest elements inside the map element, each with a ```[leafletLayer]``` input.
 The result of this is that each layer will be added to the map.
-If you add a structural directive - ```*ngFor``` or ```*ngIf``` - you can get some added flexibility when controlling layers.
+If you add a structural directive - ```@for``` or ```@if``` - you can get some added flexibility when controlling layers.
-```html
+```angular181html
 <div leaflet style="height: 300px;"
      [leafletOptions]="options">
-	<div *ngFor="let l of layers" [leafletLayer]="l"></div>
+    @for (layer of layers; track layer.id) {
+        <div [leafletLayer]="layer"></div>
+    }
 </div>
 ```
@@ -507,14 +516,14 @@ With a reference to the directive, you can invoke the ```getMap()``` function to
 This output is emitted when once when the map is initially created inside of the Leaflet directive.
 The event will only fire when the map exists and is ready for manipulation.
-```html
+```angular181html
 <div leaflet
      [leafletOptions]="options"
      (leafletMapReady)="onMapReady($event)">
 </div>
 ```
-```js
+```typescript
 onMapReady(map: Map) {
 	// Do stuff with map
 }
@@ -534,39 +543,35 @@ This means that you can create your own component or directive and inject the ``
 This will only work if your custom component/directive exists on the same DOM element and is ordered after the injected LeafletDirective, or if it is on a child DOM element.
-```html
+```angular181html
 <!-- On the same DOM element -->
-<div leaflet myCustomDirective>
-</div>
+<div leaflet myCustomDirective></div>
 <!-- On a child DOM element -->
 <div leaflet>
-	<div myCustomDirective></div>
+    <div myCustomDirective></div>
 </div>
 ```
-```js
+```typescript
 @Directive({
-	selector: '[myCustomDirective]'
+    selector: '[myCustomDirective]'
 })
 export class MyCustomDirective {
-	leafletDirective: LeafletDirective;
+    readonly #leafletDirective = inject(LeafletDirective);
-	constructor(leafletDirective: LeafletDirective) {
-		this.leafletDirective = leafletDirective;
-	}
-	someFunction() {
-		if (null != this.leafletDirective.getMap()) {
-			// Do stuff with the map
-		}
-	}
+    someFunction() {
+        if (null !== this.#leafletDirective.getMap()) {
+            // Do stuff with the map
+        }
+    }
 }
 ```
 The benefit of this approach is it's a bit cleaner if you're interested in adding some reusable capability to the existing leaflet map directive.
 As mentioned above, it might not work depending on how you are packaging your component.
-This is how the ```@asymmetrik/ngx-leaflet-draw``` and ```@asymmetrik/ngx-leaflet-d3``` packages work, so you can use them as references.
+This is how the ```@bluehalo/ngx-leaflet-draw``` and ```@bluehalo/ngx-leaflet-d3``` packages work, so you can use them as references.
 ### A Note About Change Detection
@@ -586,7 +591,7 @@ Leaflet event handlers run outside of Angular's zone, where changes to input bou
 To ensure your changes are detected and applied, you need to make those changed inside of Angular's zone.
 Fortunately, this is extremely easy.
-```js
+```typescript
 fitBounds: any = null;
 circle = circle([ 46.95, -122 ], { radius: 5000 });
@@ -613,7 +618,7 @@ Another option is to manually tell the change detector to detect changes.
 The drawback to this option is that it is less precise.
 This will trigger change detection for this component and all of its children.
-```js
+```typescript
 fitBounds: any = null;
 circle = circle([ 46.95, -122 ], { radius: 5000 });
@@ -633,73 +638,7 @@ ngOnInit() {
 	});
 }
-```
-### A Note About Markers
-If you use this component in an Angular.io project and your project uses a bundler like Webpack, you might run into issues using Markers on maps.
-The issue is related to how Leaflet manipulates the image URLs used to render markers when you are using the default marker images.
-The url manipulation is done at runtime and it alters the URLs in a way that breaks their format (this happens regardless of if you're using a file-loader or a url-loader).
-The demo contained in this project demonstrates how to get around this problem (at least in a Webpack environment).
-But, here is a rough overview of the steps taken to get them working.
-#### Webpack Marker Workaround
-1. Import the marker images in your vendor file to get Webpack to process the images in the asset pipeline
-	```js
-	import 'leaflet/dist/images/marker-shadow.png';
-	import 'leaflet/dist/images/marker-icon.png';
-	```
-1. Either host the images statically or use the file-loader Webpack plugin to generate the images.
-1. Determine the correct URL for the marker and marker-shadow images. If you're using a file hasher, you should be able to check Webpack's output for the generated images. If you are serving them directly without chunk hashing just figure out how to resolve the images on your server.
-1. Configure Leaflet to use the correct URLs as customer marker images
-	```js
-	let layer = marker([ 46.879966, -121.726909 ], {
-		icon: icon({
-			...Icon.Default.prototype.options,
-			iconUrl: '2b3e1faf89f94a4835397e7a43b4f77d.png',
-			iconRetinaUrl: '680f69f3c2e6b90c1812a813edf67fd7.png',
-			shadowUrl: 'a0c6cc1401c107b501efee6477816891.png'
-		})
-	});
-	```
-#### Angular CLI Marker Workaround
-If you build your project using the [Angular CLI](https://github.com/angular/angular-cli), you can make the default leaflet marker assets available by doing the following:
-1. Configure the CLI (by editing `angular.json`)to include leaflet assets as below. Detailed instructions can be found in the [asset-configuration](https://github.com/angular/angular-cli/blob/master/docs/documentation/stories/asset-configuration.md) documentation.
-	```json
-	{
-		...
-		"assets": [
-			"assets",
-			"favicon.ico",
-			{
-				"glob": "**/*",
-				"input": "./node_modules/leaflet/dist/images",
-				"output": "assets/"
-			}
-		],
-		...
-	}
-	```
-1. Configure Leaflet to use the correct URLs as customer marker images
-	```js
-	let layer = marker([ 46.879966, -121.726909 ], {
-		icon: icon({
-			...Icon.Default.prototype.options,
-			iconUrl: 'assets/marker-icon.png',
-			iconRetinaUrl: 'assets/marker-icon-2x.png',
-			shadowUrl: 'assets/marker-shadow.png'
-		})
-	});
-	```
+```
 ## Extensions
 There are several libraries that extend the core functionality of ngx-leaflet:
@@ -711,9 +650,9 @@ There are several libraries that extend the core functionality of ngx-leaflet:
 ## <a name="help">Getting Help</a>
 Here's a list of articles, tutorials, guides, and help resources:
 * [ngx-leaflet on Stack Overflow](https://stackoverflow.com/questions/tagged/ngx-leaflet)
-* [High-level intro to @asymmetrik/ngx-leaflet](https://github.com/BlueHalo/ngx-leaflet/wiki)
-* [Using @asymmetrik/ngx-leaflet in Angular CLI projects](https://github.com/BlueHalo/ngx-leaflet/wiki/Getting-Started-Tutorial)
-* [Integrating 3rd Party Leaflet Libraries with @asymmetrik/ngx-leaflet and @angular/cli](https://github.com/BlueHalo/ngx-leaflet/wiki/Integrating-Plugins)
+* [High-level intro to @bluehalo/ngx-leaflet](https://github.com/BlueHalo/ngx-leaflet/wiki)
+* [Using @bluehalo/ngx-leaflet in Angular CLI projects](https://github.com/BlueHalo/ngx-leaflet/wiki/Getting-Started-Tutorial)
+* [Integrating 3rd Party Leaflet Libraries with @bluehalo/ngx-leaflet and @angular/cli](https://github.com/BlueHalo/ngx-leaflet/wiki/Integrating-Plugins)
 ## Contribute