@escape-game-over/atlas 0.1.72 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.72",
+    "version": "0.1.73",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/index.ts

@@ -175,7 +175,7 @@ export {
     type LlmsItem,
     type LlmsSection,
 } from "./llms.ts";
-export type { MapPlace } from "./map.ts";
+export { googleMapsUrl, type MapPlace, type MapsTarget } from "./map.ts";
 export {
     type ArticleContent,
     buildMeta,

package/src/map.ts

@@ -29,6 +29,61 @@ export type MapFrame =
           readonly east: number;
       };
 
+/** What a Google Maps link opens on. */
+export interface MapsTarget {
+    /**
+     * The place's name, or where it is.
+     *
+     * Required even with a `placeId`: Google's link format takes the id as a
+     * refinement of a search rather than instead of one, and falls back to the
+     * search when it cannot use the id. A name searches better than a pair of
+     * numbers, so pass one where there is one.
+     */
+    readonly query: string | Coordinates;
+    /**
+     * Google's Place ID (`ChIJ…`): the listing itself, with its reviews and
+     * directions, rather than whatever a search turns up first. A short
+     * `maps.app.goo.gl` link points at the same listing, but cannot be built,
+     * checked or told apart from a link to the mall next door.
+     */
+    readonly placeId?: string;
+}
+
+/**
+ * A link that opens Google Maps on a place: its listing when it has a Place ID,
+ * otherwise a search.
+ *
+ * Google's documented, key-free format, so it works without the Maps
+ * JavaScript API and outlives any short link.
+ *
+ * @see https://developers.google.com/maps/documentation/urls/get-started#search-action
+ */
+export function googleMapsUrl(target: MapsTarget): HttpsUrl {
+    let query: string;
+    if (typeof target.query === "string") {
+        query = target.query.trim();
+        if (query === "") {
+            throw new Error(
+                "googleMapsUrl: an empty query searches for nothing."
+            );
+        }
+    } else {
+        assertCoordinates(target.query, "googleMapsUrl");
+        query = `${target.query.latitude},${target.query.longitude}`;
+    }
+
+    const params = new URLSearchParams({ api: "1", query });
+    if (target.placeId !== undefined) {
+        if (target.placeId.trim() === "") {
+            throw new Error(
+                `googleMapsUrl: "${query}" has an empty Place ID; leave it out to search instead.`
+            );
+        }
+        params.set("query_place_id", target.placeId);
+    }
+    return `https://www.google.com/maps/search/?${params.toString()}`;
+}
+
 /** Street level: close enough to find the door. */
 const POINT_ZOOM = 15;