@fieldia/map 0.19.0 → 0.20.0

package/src/lib/address-parts.d.ts

@@ -1,9 +1,16 @@
+import type { Locale } from '@fieldia/core';
+import type { PlaceFound, SearchRequest } from './providers';
 /**
- * An address in its parts, as Fieldia's address field (`json.address`) keeps
- * one: the street with its number, the city, the region (a state, a
- * governorate), the postcode, and the country as its ISO code ("EG"). Each
- * provider names them its own way; they are read into these here, asked for
- * only by a search that wants them (`SearchRequest.parts`).
+ * How each provider's addresses read, loaded with the first search that
+ * needs it (an address field's; any of Azure's or Google's), never with a
+ * page: an address in its parts, as Fieldia's address field
+ * (`json.address`) keeps one (the street with its number, the city, the
+ * region, a state or a governorate, the postcode, and the country as its ISO
+ * code, "EG"); Azure's and Google's places on two lines, in the page's
+ * language; and where a suggestion picked is, for those whose suggestions
+ * carry no place. Each provider names the parts its own way: what each
+ * answered in Egypt, Saudi Arabia, the UAE and Jordan on 12 Oct 2026 is
+ * read here.
  */
 export interface AddressParts {
     street?: string;
@@ -16,13 +23,124 @@ export interface AddressParts {
 export declare const photonParts: (p: unknown) => AddressParts | undefined;
 /** Nominatim's `address` (with `addressdetails=1`): a town or a village where there is no city. */
 export declare const nominatimParts: (a: unknown) => AddressParts | undefined;
-/** Azure's `address`: its own street line when it has one, its first admin district the region; its country's code is `ISO`, or `iso` in some answers. */
-export declare const azureParts: (a: unknown) => AddressParts | undefined;
-/** Google's `addressComponents`, each by its type: the country by its short code. */
-export declare const googleParts: (components: unknown) => AddressParts | undefined;
-/** Mapbox's `context`: its address's own line (number and street), or the street alone. */
+/** Mapbox's `context`: its address's own line (number and street, in its country's order), or the street alone. */
 export declare const mapboxParts: (p: unknown) => AddressParts | undefined;
 /** Only places in the countries asked for, when some are: for a provider that cannot be asked to keep to them. */
 export declare const inCountries: <T extends {
     parts?: AddressParts;
 }>(places: T[], countries?: string[]) => T[];
+/**
+ * The countries a provider can be asked to keep to: ISO codes, each once,
+ * "UK" read as "GB" (as every provider's parts name it). A code no one
+ * knows ("XX", "EGY") is left out and said once: Azure and Google refuse a
+ * whole search for one.
+ */
+export declare function knownCountries(countries: string[] | undefined): string[];
+/** The countries Google is asked to keep to (`includedRegionCodes`): 15 at most, as it refuses a whole search for more; with more, none, said once. */
+export declare function googleRegions(countries: string[] | undefined): string[];
+/** What one of Azure's places is, by its type: a street (an address, a road), an area (a town, a district, a governorate), or a place with a name of its own (a station, a park, a mall). */
+type Level = 'street' | 'area' | 'named';
+type LatLngAt = {
+    lat: number;
+    lng: number;
+};
+/** A place of Azure's, with what locating it takes: its address as Azure gave it, its level, its street line or its area's own name, and where the search looked. */
+export interface AzurePlace extends PlaceFound {
+    country: string;
+    azure: {
+        address: unknown;
+        level: Level;
+        street: string;
+        area?: string;
+        type?: string;
+        near?: LatLngAt;
+    };
+}
+/** Azure's places on two lines: the street, or the place's own name (a quarter's, a town's), then where it is; their parts when asked. */
+export declare function azurePlaces(found: unknown, locale: Locale, typed?: string, withParts?: boolean, near?: LatLngAt): AzurePlace[];
+/** A point named by Azure: its first address, in order. */
+export declare function azureNamed(found: unknown, locale: Locale): string;
+type Ask = (params: Record<string, string | number | undefined>) => Promise<unknown>;
+/**
+ * Azure's suggestions: nearest the place the page gives first, or the whole
+ * world's by prominence when it gives none; kept to the countries the page
+ * names by Azure itself (`countryRegion`), one request for each (a tenth of
+ * a Search transaction each; a list of them answers nothing), taken in
+ * turn, five in all. For an address field (`addresses`), no postcodes alone,
+ * and the addresses and areas first, the places with names of their own
+ * (a station, a park) after them, as Azure's types say. A row that reads as
+ * one before it is left out, as one that says less of the same place than
+ * another is. The word for a district typed before its name ("حي الروضة")
+ * is left out of the words asked, as Azure names its districts without it
+ * (with it, Azure lists other towns' streets and districts named with the
+ * word, and none of Riyadh's Al Rawdah); the words are asked as typed only
+ * when that finds nothing.
+ */
+export declare function azureSearch(autocomplete: Ask, request: SearchRequest): Promise<AzurePlace[]>;
+/**
+ * Where a suggestion of Azure's is (its suggestions carry no place), asked
+ * of its geocoding, the hits in the suggestion's own country and admin
+ * districts kept (`fits`; "Al Rawdah" in Riyadh's governorate, never in
+ * Al Wasiah's).
+ *
+ * A street, by its own address in Azure's structured form: its street line
+ * (never with a house number Azure made up), its own district for its
+ * locality where it names one below its town (its neighbourhood, the
+ * district its line names, "Kamel El Shenawy, Garden City"), then its
+ * locality, its admin districts, postcode and country; then by its two
+ * lines (`query`). Of each answer's streets, the one that names its
+ * district; else one in the district's own box as Azure has it (a little
+ * beyond it, as its point is a stretch's middle), asked for once; never a
+ * street of the name in another district (Azure's first "Kamel El Shenawy"
+ * is New Cairo's, 25 km from Garden City's), nor, for a street named by its
+ * number alone ("10 41 Street | Abu Tina"), one that does not say it is in
+ * its district where Azure knows none. Found nowhere so, its district
+ * (`precise: false`), else its town.
+ *
+ * An area by its own name (its neighbourhood, the place its line names, its
+ * locality; a governorate named for its town as the town: "Sohag", whose
+ * division's middle is 57 km from the city), never by its postcode (one of
+ * a town's many: Azure gives Tanta's 31111 for Tanta), or by its two lines
+ * where its neighbourhood is not its locality; a place with a name of its
+ * own by its two lines. Of places of one kind and name (Abu Dhabi's Al
+ * Bateen and Al Ain's), the one nearest where the search looked; found
+ * nowhere, the town it is in (`precise: false`).
+ *
+ * It is precise when the hit is the place itself (`isItself`), a street's
+ * in its own district: where Azure knows no box for the district, a street
+ * it marks `Ambiguous` (several of the words) is only near, as one of a
+ * number is unless it says it is in its district. Otherwise only near it.
+ * Never a place anywhere else: none is found then.
+ * A suggestion that names no region ("البرشاء 2", which Azure lists beside
+ * the same in Dubai) takes its city and region from the place found.
+ */
+export declare function azureLocate(geocode: Ask, place: AzurePlace, locale: Locale): Promise<{
+    precise?: false | undefined;
+    parts?: {
+        city?: string;
+        region?: string;
+        street?: string;
+        postcode?: string;
+        country?: string;
+    } | undefined;
+    address: string;
+    lat: number;
+    lng: number;
+}>;
+/**
+ * Google's `addressComponents`, each by its type: the country by its short
+ * code. Its number where Google's own line (`formatted`) puts it: before the
+ * street in Egypt and Saudi Arabia ("7524 King Fahd Rd"), after it in Jordan
+ * and Germany ("Rainbow St. 15"). Its city its locality; Egypt's streets have
+ * none, and their district stands for it ("Qasr El Nil", "Maadi"), by its
+ * name alone in Arabic too ("الدقي", not "قسم الدقي", its police district's).
+ */
+export declare const googleParts: (components: unknown, formatted?: unknown) => AddressParts | undefined;
+/**
+ * Google's suggestions: each one's name, and where it is; for an address
+ * field, the addresses first (their types say "geocode"), the shops and
+ * buildings after them. Each is located when picked, through `details`
+ * (Place Details), which ends its session (`end`), as picking it does.
+ */
+export declare function googlePlaces(answer: unknown, { locale, addresses, parts }: SearchRequest, details: (placeId: string) => Promise<unknown>, end: () => void): PlaceFound[];
+export {};