@escape-game-over/atlas 0.1.4 → 0.1.6

package/docs/NOT-BUILT.md

@@ -180,20 +180,28 @@ exactly the set displayed — never a number typed in beside a shorter list.
 
 ### Should `CurrencyCode` and `CountryCode` spell out the ISO lists?
 
-**Not now.**
+**`CountryCode` now does. `CurrencyCode` still does not, for the reason that
+used to cover both.**
 
-Both are shapes rather than vocabularies — `` `${Letter}${Letter}${Letter}` ``
-and `` `${Letter}${Letter}` `` — so `"XYZ"` and `"ZZ"` type-check. ISO 4217 has
+Both were shapes rather than vocabularies — `` `${Letter}${Letter}${Letter}` ``
+and `` `${Letter}${Letter}` `` — so `"XYZ"` and `"ZZ"` type-checked. ISO 4217 has
 around 180 active codes and ISO 3166-1 alpha-2 has 249; both are small, closed
 and effectively frozen, so enumerating them is possible in a way the [IANA
 language registry](https://www.iana.org/assignments/language-subtag-registry) is
 not — which is the case `LanguageTag` in `config.ts` declines and says why.
 
-Left as shapes because the mistake is not one anyone has made: a currency is
-written once per project, beside the prices it applies to, and a wrong one is
-visible the first time a page renders. That is a different risk from a typo in a
-directive nobody reads. Worth revisiting if a project ever computes a code
-rather than writing it.
+What moved is not the risk, it is the reason to hold the list at all. A country
+menu needs the codes *as data* — `countriesFor` renders and sorts them per
+locale — and once the list exists, deriving the type from it is free and the
+shape is strictly worse: it admitted 676 strings for 250 countries, including
+the withdrawn codes (`SU`, `YU`, `AN`) that look plausible enough to be typed by
+accident. So `CountryCode` is now `(typeof COUNTRY_CODES)[number]`, defined in
+`countries.ts` and re-exported from `contact.ts` beside `PostalAddress`.
+
+`CurrencyCode` stays a shape, because nothing needs a currency *list*: a
+currency is written once per project, beside the prices it applies to, and a
+wrong one is visible the first time a page renders. Enumerate it the day
+something renders a currency picker, and not before.
 
 ### Should `@type` be checked against schema.org's vocabulary?
 
@@ -219,6 +227,73 @@ type could — a property that is not valid for the type it sits on.
 
 ## Answers that will not change on their own
 
+### Should a paragraph be authored as an array of translation keys?
+
+**No. One sentence is one message, and the styling lives in the copy as
+`[marks]`. `content/` carries the parser, the runs and `plain()`; nothing
+carries a `ContentItem[]`.**
+
+This is the shape the sibling B2C template uses, and it is the one thing from
+there that was deliberately not ported — so the reasoning is here, because
+reading those configs is what prompts the question. A paragraph is written as an
+array of `{ type, content }` objects, each `content` a translation key, and the
+renderer concatenates them in the order the array was typed:
+
+```ts
+subtitle: [
+    { type: "text", content: "hero.subtitle_text_1" },
+    { type: "bold", content: "hero.subtitle_text_2" },
+    { type: "text", content: "hero.subtitle_text_3" },
+    // …through _7
+]
+```
+
+**It fixes two things copy is not allowed to fix.** Word order, which differs
+per language — the array says the bold clause comes second, in every locale,
+forever. And the *number of runs*, which differs more: a clause English spends
+four fragments on is one word in Greek, and there is no way to write that in an
+array whose length was decided by whoever typed the English. The extra keys get
+padded with empty strings or the spare ones go untranslated, and either way the
+translator is editing around a data structure instead of writing a sentence.
+
+The `spaceAfter: true` flag on those objects is the tell. It exists because the
+runs are concatenated with nothing between them, so a sentence split across keys
+needs someone to remember which fragments end in a space — a per-fragment
+decision that is invisible until it renders. With one message the spaces are
+just in the copy.
+
+What replaces it is a mark in the message: `"Book [b]up to six[/b] at
+[a:venue]our venue[/a]."`. Each language moves them where its grammar wants
+them, `rich()` returns the runs, and the renderer styles them. The mark set is
+compared across locales by the machinery that already compares `{placeholders}`
+— see `Tokens` in `i18n/placeholders.ts` — so a translation that drops the link
+fails the build rather than the page. That check is the reason marks are safe to
+put in copy at all, and it is what the array shape genuinely did buy: with the
+structure in config, no locale *could* lose a link. Marks had to earn that back.
+
+**A mark names a slot, never a destination**, and that distinction is the second
+thing the array shape got right and the first version of this got wrong. `venue`
+above is a name the call site fills — `rich(key, { venue: "contact" })` — so the
+route id is checked against the route table like every other link in the package,
+it is written once rather than once per language, and an external URL never
+enters a file that translators edit. Copy holding `[a:https://…]` in ten
+languages is ten unchecked copies of an address, and the eleventh is the one
+somebody "corrects".
+
+**What is still fine to build.** Composing runs in code: a `Span[]` is the
+resolved type, already plain strings and finished hrefs, so a project assembling
+a line from config values — a price, a phone number, a room name — builds one
+directly and needs nothing from `rich()`. And a list is still an array: spans are
+inline, so bullets are `readonly RichText[]` in the project's own config, which
+is what the old `bulletList` run should become.
+
+**What is not a reason, and was the strongest argument for porting it.** That
+around 6,300 authored runs across fifty-four deployments would migrate verbatim.
+They would — and they would carry the fragmentation with them into a codebase
+whose whole claim is that a translation cannot silently go wrong. The migration
+is happening once; this is the moment it costs least to fix, and every store
+collapsed to marks is a store whose copy a translator can finally read.
+
 ### Should lib carry the consent *banner* as well as the tags?
 
 **No — and the line between the two halves is the point.**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.4",
+    "version": "0.1.6",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -39,7 +39,7 @@
     "scripts": {
         "test": "npm run test:types && npm run test:unit && npm run test:examples",
         "test:types": "tsc --noEmit && astro check --root checks/astro",
-        "test:unit": "vitest run",
+        "test:unit": "vitest run --coverage",
         "test:watch": "vitest",
         "test:examples": "npm run test --workspaces",
         "lint": "biome check .",
@@ -55,6 +55,7 @@
     "devDependencies": {
         "@biomejs/biome": "2.5.10",
         "@types/node": "26.3.0",
+        "@vitest/coverage-istanbul": "4.1.11",
         "astro": "7.2.6",
         "typescript": "6.0.3",
         "vitest": "4.1.11"

package/src/contact.ts

@@ -1,4 +1,5 @@
-import type { Digit, Letter } from "./types.ts";
+import type { CountryCode } from "./countries.ts";
+import type { Digit } from "./types.ts";
 import { warn } from "./warn.ts";
 
 /**
@@ -81,6 +82,30 @@ export function formatPhone(phone: PhoneNumber): string {
     return `+${phone.code} ${phone.number}`;
 }
 
+/**
+ * A number in E.164: a plus, then digits.
+ *
+ * Named for the reason `HttpsUrl` is — so that everything built from one
+ * inherits the guarantee rather than re-stating it. `TelUrl` is a template on
+ * this, so a `tel:` cannot be assembled from a number that never had a country
+ * code, which is the whole thing `e164Of` is checking for.
+ */
+export type E164 = `+${string}`;
+
+/**
+ * A `tel:` link, as a shape.
+ *
+ * Beside `E164` and `EmailAddress` rather than in `url.ts` with `HttpsUrl` and
+ * `UrlPath`: those two are addresses of *pages*, and half of what lib does is
+ * build them from a route table. These are neither — they are the two schemes
+ * this file produces from a phone number and an address, and they belong with
+ * the values they are made of.
+ */
+export type TelUrl = `tel:${E164}`;
+
+/** A `mailto:` link, as a shape. @see {@link TelUrl} */
+export type MailtoUrl = `mailto:${EmailAddress}`;
+
 /**
  * The number as a phone dials it: `tel:+390600000000`.
  *
@@ -92,7 +117,7 @@ export function formatPhone(phone: PhoneNumber): string {
  * and nothing is removed, so this and `formatPhone` are two renderings of one
  * value rather than two opinions about it.
  */
-export function telHref(phone: PhoneNumber): string {
+export function telHref(phone: PhoneNumber): TelUrl {
     return `tel:${e164(phone)}`;
 }
 
@@ -117,25 +142,82 @@ export function telHref(phone: PhoneNumber): string {
  * `replace(/^0+/, "")` also took *every* leading zero rather than one trunk
  * digit, so `007…` became `7…`.
  */
-export function e164(phone: PhoneNumber): string {
+export function e164(phone: PhoneNumber): E164 {
     return `+${phone.code}${phone.number.replace(/\D/g, "")}`;
 }
 
+/**
+ * The same, for a number that arrives already written out: `"+39 06 0000 0000"`
+ * → `"+390600000000"`. `undefined` if it is not in international form.
+ *
+ * Beside `e164` rather than wherever it is called, because the two answer one
+ * question from different inputs and the *rule* is the paragraph above: only
+ * punctuation goes, nothing is added, and no leading zero is touched. Written
+ * out twice, that rule survives in one copy and quietly stops being true in the
+ * other — and the version that stops being true is the one nobody re-reads,
+ * because both keep producing a `tel:` that looks fine.
+ *
+ * The structured form is the one to prefer where there is a choice: `code` and
+ * `number` cannot be run together wrongly, and `formatPhone` renders the same
+ * value for a reader. This is for the case where there is no choice — a number
+ * inside a sentence, where the copy is what holds it.
+ *
+ * **International form is required, and that is the whole check.** A local
+ * number dials from inside the country and silently fails everywhere else,
+ * which for a venue is precisely the visitor worth reaching. It is also
+ * invisible on the page, because the number *reads* correctly — so the refusal
+ * has to happen here, where the `+` either is or is not.
+ */
+export function e164Of(written: string): E164 | undefined {
+    if (!written.trimStart().startsWith("+")) return undefined;
+    return `+${written.replace(/\D/g, "")}`;
+}
+
 /** An email address, which is only ever used whole. */
 export type EmailAddress = `${string}@${string}`;
 
-export function mailtoHref(email: EmailAddress): string {
+/**
+ * The runtime half of `EmailAddress`, written as a guard so the check that
+ * refuses is also the check that narrows — as `isHttpsUrl` is for `HttpsUrl`.
+ *
+ * Needed because an address does not always arrive as a literal. One written
+ * into copy and pulled back out by `rich()` is a `string` as far as the types
+ * are concerned, and without this the call site either casts — asserting what it
+ * has not tested — or invents its own idea of what an address looks like, which
+ * is how two of them end up disagreeing.
+ *
+ * **`includes("@")` is exactly what the type says, and not less.** The shape is
+ * `` `${string}@${string}` ``, whose two halves may each be empty, so it admits
+ * `"@x"` and `"x@"` — and so does this. That is the point rather than a gap:
+ * the pair agree, and a stricter runtime check would start rejecting values the
+ * compiler had already accepted. Validating an address properly is famously not
+ * a regex, and a half-strict one here would only move where the disagreement
+ * lives. The `mailto:` either opens with something in the To: field or it does
+ * not, which is the failure this is guarding against.
+ */
+export function isEmailAddress(value: string): value is EmailAddress {
+    return value.includes("@");
+}
+
+/**
+ * The `mailto:` for an address.
+ *
+ * The return type is narrowed rather than left as `string` so that anything
+ * carrying one — `Span`'s email run, say — can demand a scheme it did not have
+ * to build itself.
+ */
+export function mailtoHref(email: EmailAddress): MailtoUrl {
     return `mailto:${email}`;
 }
 
 /**
- * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ * Re-exported so an address and its country code stay one import.
  *
- * Two uppercase letters, which is what `addressCountry` is read as. A name —
- * `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
- * identifier for one, and belongs in the sentence a page prints, not here.
+ * Defined beside the list it is read from — see `countries.ts`. Imported at the
+ * top as well: `export … from` forwards a name without binding it here, and
+ * `PostalAddress` below needs it in scope.
  */
-export type CountryCode = `${Letter}${Letter}`;
+export type { CountryCode };
 
 /**
  * Where a place is, to the precision a map needs.

package/src/content/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Copy that carries styling, without carrying markup.
+ *
+ * A paragraph is one message, marked up in the copy itself — see `marks.ts` for
+ * why it cannot be an array of keys — and this module turns it into runs a
+ * project renders however it likes. Lib owns which runs exist and what they say;
+ * the project owns what they look like.
+ *
+ * ```ts
+ * // config/messages.ts
+ * "about.intro": {
+ *     "en-US": "Book [v:accent]up to six[/v] at [a:venue]our venue[/a].",
+ * }
+ *
+ * // a view
+ * const rich = site.rich(locale);
+ * <RichText spans={rich("about.intro")} />
+ *
+ * // the same sentence, where a string is what fits
+ * description: plain(rich("about.intro"))
+ * ```
+ *
+ * There is no authored `ContentItem[]`. Where a project needs to compose runs
+ * itself — a price, a number pulled from config — it builds `Span[]` directly,
+ * which is already the resolved shape and needs nothing from here.
+ */
+
+export { assertNoMarks, type ParsedSpan, parseMarks } from "./marks.ts";
+export {
+    createPlainText,
+    createRichText,
+    type LinkResolver,
+    type LinkTarget,
+    type PlainTextFor,
+    plain,
+    type RichText,
+    type RichTextFor,
+    type RichTextOptions,
+    type Span,
+} from "./rich.ts";