@geosdi/ngx-geocoding 1.2.1 → 2.0.0

package/README.md

@@ -1,6 +1,4 @@
-# NgxGeocoding
-
-# General information
+# @geosdi/ngx-geocoding
 
 Address search for Angular, from one or more sources tried **in order**.
 
@@ -17,11 +15,10 @@ that does not.
 
 `npm i @geosdi/ngx-geocoding --save`
 
-It depends on :
+Peer dependencies:
 
-    "@angular/common": ">=20.0.0",
-    "@angular/core": ">=20.0.0",
-    "typescript": ">=5.0.0",
+    "@angular/common": ">=22.0.0",
+    "@angular/core": ">=22.0.0",
     "rxjs": ">=7.8.0"
 
 Nominatim is called through `HttpClient`, so the application must provide it —
@@ -103,10 +100,12 @@ Two things live outside this library.
   two copies of it in the same page;
 - **`libraries=places`** — without it only the third step of the cascade
   (`Geocoder`) can answer;
-- **`language`** decides the language of the suggestions, and this is the only
-  place to set it: the SDK request has no parameter for it;
+- **`language`** decides the language of the suggestions: the library passes no
+  language of its own to the SDK, so the one in the script tag is used;
 - **`defer` is fine**: the library waits for the SDK up to 10 s, polling every
-  100 ms, so a search typed right after startup does not get lost.
+  100 ms, so a search typed right after startup does not get lost. Without
+  `libraries=places` the wait happens twice, once per Places step, so the first
+  search reaches the `Geocoder` only after about 20 s.
 
 **2. The Google Cloud project**, where the key must have:
 
@@ -178,6 +177,10 @@ export class SearchComponent {
         }
       });
   }
+
+  private moveMap(lat: number, lon: number): void {
+    // the application's own: for example map.setView([lat, lon], 16)
+  }
 }
 ```
 
@@ -208,13 +211,16 @@ search" are two different things, and a search bar has to tell them apart.
 | `subjectLocation`  | subject to notify location               |
 | `subjectRemove`    | subject to notify remove location        |
 
+Only `subjectNoResults` is emitted by the library. `subjectLocation` and `subjectRemove` are
+channels for the application: nothing in the library calls `next` on them.
+
 ## Troubleshooting
 
 Every fallback is logged with `console.warn`, prefixed `[ngx-geocoding]`.
 
-| what the console says                       | what it means                                                                      |
+| what you see                                | what it means                                                                      |
 | ------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `SDK Maps senza la libreria 'places'`       | `libraries=places` missing from the script tag, or no SDK in the page              |
+| `SDK Maps senza la libreria 'places'`       | `libraries=places` missing from the script tag, or no SDK in the page; ~20 s wait  |
 | `SDK Maps senza il Geocoder`                | no SDK in the page at all                                                          |
 | `REQUEST_DENIED`                            | product not enabled on the Cloud project, or referrer outside the key restrictions |
 | `OVER_QUERY_LIMIT`                          | quota or billing on the Google project                                             |
@@ -223,3 +229,25 @@ Every fallback is logged with `console.warn`, prefixed `[ngx-geocoding]`.
 
 A source that refused is not asked again until the page is reloaded, so a fix on
 the Cloud console needs a reload to be seen.
+
+**Any error counts as a refusal, including a transient one.** A request that fails
+because the network dropped for a moment, or a `429` from the public Nominatim
+(easy to get with search-as-you-type), switches that source off for the session
+just like a `REQUEST_DENIED` does. With `sources: ["nominatim"]` — the default —
+every following search then fails with `Nessuna sorgente di geocoding disponibile`
+until the page is reloaded. Debounce the input, and keep more than one source
+where you can.
+
+## Changes in 2.0.0
+
+- **A major version** because the peer dependencies now ask for Angular 22:
+  an application on an older Angular can no longer install it. The API is
+  unchanged unless a point below says otherwise.
+- `typescript` is no longer a peer dependency: nothing in the package
+  imports it.
+- **The Angular peer dependencies are `>=22.0.0`**: the library is compiled and tested with
+  Angular 22 only, so it no longer claims to install on older versions.
+- Compiled with Angular 22. The peer dependencies were already correct and are unchanged.
+- This README: the title of the package, which events the library emits, and what a transient
+  error does to a source.
+- The code is unchanged.