@escape-game-over/atlas 0.1.74 → 0.1.76

package/docs/client-scripts.md

@@ -581,7 +581,9 @@ googleEvent("form_submissions_contact"); // does not compile
 A name nobody declared does not compile, so a typo cannot quietly become a
 second event in a report — which is why this is not a `string` with the standard
 names offered for autocomplete. Data declared with a required field is required
-at every call. The interfaces are `GoogleCustomEvents`, `MetaCustomEvents`,
+at every call. A Google declaration may reuse a recommended name —
+`generate_lead` with an agency's own parameters, say — and then takes what was
+declared instead of GA4's. The interfaces are `GoogleCustomEvents`, `MetaCustomEvents`,
 `TikTokCustomEvents`, `UmamiEvents`, `DripEvents` and `ClarityEvents`; Clarity
 carries a name only, so its entries are all `undefined`. Snap and Axon take no
 declarations because they accept no names but their own.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.74",
+    "version": "0.1.76",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -58,7 +58,7 @@
     },
     "devDependencies": {
         "@biomejs/biome": "2.5.15",
-        "@types/node": "26.6.3",
+        "@types/node": "26.6.4",
         "@vitest/coverage-istanbul": "5.0.3",
         "astro": "7.3.5",
         "typescript": "6.0.3",

package/src/address-formats.ts

@@ -26,7 +26,28 @@ export type AddressPart =
 export type AddressLayout = readonly (readonly AddressPart[])[];
 
 /**
- * How a country lays out an address.
+ * The script an address is written in: the country's own, or Latin letters.
+ * Some countries order the two differently: `東京都` before the street, but
+ * `Tokyo` after it.
+ */
+export type AddressScript = "local" | "latin";
+
+/**
+ * How a country lays out an address written in `script`: its Latin-script
+ * layout where it has one of its own, else the local one.
+ */
+export function addressLayout(
+    country: CountryCode,
+    script: AddressScript = "local"
+): AddressLayout {
+    return (
+        (script === "latin" ? latinAddressLayout(country) : undefined) ??
+        localAddressLayout(country)
+    );
+}
+
+/**
+ * How a country lays out an address in its own script.
  *
  * Converted once from Google's address metadata, the dataset behind
  * libaddressinput (Apache License 2.0), fetched 2026-10-02 one country at a
@@ -50,7 +71,7 @@ export type AddressLayout = readonly (readonly AddressPart[])[];
  * To update one, take its format from that address again and convert it the
  * same way. A country listed twice is caught by Biome's `noDuplicateCase`.
  */
-export function addressLayout(country: CountryCode): AddressLayout {
+function localAddressLayout(country: CountryCode): AddressLayout {
     switch (country) {
         case "AD":
         case "AT":
@@ -667,3 +688,82 @@ export function addressLayout(country: CountryCode): AddressLayout {
             return [[{ field: "street" }], [{ field: "locality" }]];
     }
 }
+
+/**
+ * How a country lays out an address in Latin letters, where that is not its
+ * local layout; `undefined` where it is.
+ *
+ * Google's `lfmt` field, from the same metadata and converted the same way as
+ * `localAddressLayout`. Fourteen countries have one; only these six differ from
+ * their `fmt` once the fields `PostalAddress` does not carry are dropped. The
+ * other eight (AE, AM, EG, MO, RU, TH, UA, VN) fall through to the local one.
+ */
+function latinAddressLayout(country: CountryCode): AddressLayout | undefined {
+    switch (country) {
+        case "CN":
+        case "KP":
+            return [
+                [{ field: "street" }],
+                [{ field: "locality" }],
+                [{ field: "region" }, { field: "postalCode", separator: ", " }],
+            ];
+        case "HK":
+            return [
+                [{ field: "street" }],
+                [{ field: "locality" }],
+                [{ field: "region" }],
+            ];
+        case "JP":
+            return [
+                [{ field: "street" }, { field: "region", separator: ", " }],
+                [{ field: "postalCode" }],
+            ];
+        case "KR":
+            return [
+                [{ field: "street" }],
+                [{ field: "locality" }],
+                [{ field: "region" }],
+                [{ field: "postalCode" }],
+            ];
+        case "TW":
+            return [
+                [{ field: "street" }],
+                [
+                    { field: "locality" },
+                    { field: "region", separator: ", " },
+                    { field: "postalCode", separator: " " },
+                ],
+            ];
+        default:
+            return undefined;
+    }
+}
+
+/**
+ * How a country writes its address on one line: the groups `addressLine`
+ * joins, in the order a sentence or a listing runs them.
+ *
+ * `addressLayout` for every country but those below, where a line of text runs
+ * in another order than the envelope. Google's metadata has envelope layouts
+ * only, so these are written by hand; each says why.
+ */
+export function inlineAddressLayout(
+    country: CountryCode,
+    script: AddressScript = "local"
+): AddressLayout {
+    switch (country) {
+        // The envelope goes town, street, postal code, each on its own line; a
+        // line of text goes postal code and town first, the way the company
+        // register writes it: `1132 Budapest, Victor Hugo utca 16`.
+        case "HU":
+            return [
+                [
+                    { field: "postalCode" },
+                    { field: "locality", separator: " " },
+                ],
+                [{ field: "street" }],
+            ];
+        default:
+            return addressLayout(country, script);
+    }
+}

package/src/astro/google-event.ts

@@ -78,22 +78,24 @@ export interface GoogleEventData {
 }
 
 /**
- * A recommended event takes GA4's parameters; `purchase` without its three
- * reports a sale of nothing, possibly twice. A declared one takes what the
- * project declared.
+ * A declared event takes what the project declared — checked first, so a
+ * project can declare a recommended name too, when its Tag Manager wants that
+ * name with its own parameters (an agency's `generate_lead`, say). Otherwise a
+ * recommended event takes GA4's parameters; `purchase` without its three
+ * reports a sale of nothing, possibly twice.
  */
 type GoogleEventArgs<E extends GoogleEventName> =
-    E extends GoogleRecommendedEvent
-        ? E extends "purchase"
-            ? [
-                  data: GoogleEventData & {
-                      value: number;
-                      currency: CurrencyCode;
-                      transaction_id: string;
-                  },
-              ]
-            : [data?: GoogleEventData]
-        : EventDataArgs<GoogleCustomEvents[E & keyof GoogleCustomEvents]>;
+    E extends DeclaredEvent<GoogleCustomEvents>
+        ? EventDataArgs<GoogleCustomEvents[E]>
+        : E extends "purchase"
+          ? [
+                data: GoogleEventData & {
+                    value: number;
+                    currency: CurrencyCode;
+                    transaction_id: string;
+                },
+            ]
+          : [data?: GoogleEventData];
 
 /**
  * Records an event with Google — a lead sent, a booking made — through

package/src/contact.ts

@@ -1,4 +1,9 @@
-import { addressLayout } from "./address-formats.ts";
+import {
+    type AddressLayout,
+    type AddressScript,
+    addressLayout,
+    inlineAddressLayout,
+} from "./address-formats.ts";
 import type { CountryCode } from "./countries.ts";
 import type { Digit } from "./types.ts";
 import { warn } from "./warn.ts";
@@ -334,10 +339,56 @@ export interface PostalAddress {
  * own: no postal code, no `CH-`. Letter case is the caller's: some countries
  * want the town in capitals on an envelope, which is not how a page should
  * print it.
+ *
+ * `script` is the script the address is written in, which the caller knows and
+ * the record does not: a Tokyo address in Latin letters runs street first,
+ * `["1-1 Chiyoda, Tokyo", "100-0001"]`, where in Japanese it runs prefecture
+ * first. Only the six countries Google gives a different Latin layout care.
  */
-export function addressLines(address: PostalAddress): readonly string[] {
+export function addressLines(
+    address: PostalAddress,
+    options: AddressFormatOptions = {}
+): readonly string[] {
+    return render(address, addressLayout(address.country, options.script));
+}
+
+/** How `addressLines` writes an address. */
+export interface AddressFormatOptions {
+    /** The script the address is written in. Defaults to `"local"`. */
+    readonly script?: AddressScript;
+}
+
+/** How `addressLine` writes an address. */
+export interface AddressLineOptions extends AddressFormatOptions {
+    /** Between the groups the line joins. Defaults to `", "`. */
+    readonly separator?: string;
+}
+
+/**
+ * The address on one line, for where there is room for only one: a venue card,
+ * an `llms.txt` entry.
+ *
+ * Not always `addressLines` joined: where a country writes a line of text in
+ * another order than an envelope, it follows the line of text. Hungary's
+ * envelope goes `Budapest` / `Victor Hugo utca 16` / `1132`; this gives `1132
+ * Budapest, Victor Hugo utca 16`.
+ */
+export function addressLine(
+    address: PostalAddress,
+    options: AddressLineOptions = {}
+): string {
+    const { script, separator = ", " } = options;
+    return render(address, inlineAddressLayout(address.country, script)).join(
+        separator
+    );
+}
+
+function render(
+    address: PostalAddress,
+    layout: AddressLayout
+): readonly string[] {
     const lines: string[] = [];
-    for (const parts of addressLayout(address.country)) {
+    for (const parts of layout) {
         let line = "";
         for (const part of parts) {
             if ("text" in part) {
@@ -353,14 +404,3 @@ export function addressLines(address: PostalAddress): readonly string[] {
     }
     return lines;
 }
-
-/**
- * `addressLines` on one line, for where there is room for only one: a venue
- * card, an `llms.txt` entry.
- */
-export function addressLine(
-    address: PostalAddress,
-    separator: string = ", "
-): string {
-    return addressLines(address).join(separator);
-}

package/src/index.ts

@@ -12,6 +12,7 @@
  * ```
  */
 
+export type { AddressScript } from "./address-formats.ts";
 export {
     CONSENT_CATEGORIES,
     CONSENT_MONTHS,
@@ -51,6 +52,8 @@ export type {
     SiteConfigShape,
 } from "./config.ts";
 export {
+    type AddressFormatOptions,
+    type AddressLineOptions,
     addressLine,
     addressLines,
     assertCoordinates,