@mailwoman/codex 6.0.0 → 6.2.0

package/out/index.d.ts

@@ -15,7 +15,10 @@
  *   Systems are exposed as namespaces (`import { us } from "@mailwoman/codex"`) and as subpaths
  *   (`import { lookupStreetSuffix } from "@mailwoman/codex/us"`). The cross-system
  *   `candidateSystemsForPostcode` (the inverse of the per-slice postcode patterns) is a top-level
- *   export.
+ *   export. `levels` is the per-locale LEVEL/floor ordinal-semantics table (#1100) — like
+ *   `candidateSystemsForPostcode`, it's inherently multi-locale, so it lives at the codex root
+ *   (`./level-semantics.ts`) and is namespaced rather than given its own `@mailwoman/codex/<x>`
+ *   subpath.
  */
 export { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem, type AddressSystemConventions, } from "./address-system-conventions.ts";
 export * as au from "./au/index.ts";
@@ -24,6 +27,7 @@ export * as de from "./de/index.ts";
 export * as fr from "./fr/index.ts";
 export * as gb from "./gb/index.ts";
 export * as jp from "./jp/index.ts";
+export * as levels from "./level-semantics.ts";
 export * as nz from "./nz/index.ts";
 export { candidateSystemsForPostcode, type SystemCode } from "./postcode-systems.ts";
 export * as us from "./us/index.ts";

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,wBAAwB,GAC7B,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,wBAAwB,GAC7B,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,sBAAsB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}

package/out/index.js

@@ -15,7 +15,10 @@
  *   Systems are exposed as namespaces (`import { us } from "@mailwoman/codex"`) and as subpaths
  *   (`import { lookupStreetSuffix } from "@mailwoman/codex/us"`). The cross-system
  *   `candidateSystemsForPostcode` (the inverse of the per-slice postcode patterns) is a top-level
- *   export.
+ *   export. `levels` is the per-locale LEVEL/floor ordinal-semantics table (#1100) — like
+ *   `candidateSystemsForPostcode`, it's inherently multi-locale, so it lives at the codex root
+ *   (`./level-semantics.ts`) and is namespaced rather than given its own `@mailwoman/codex/<x>`
+ *   subpath.
  */
 export { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem, } from "./address-system-conventions.js";
 export * as au from "./au/index.js";
@@ -24,6 +27,7 @@ export * as de from "./de/index.js";
 export * as fr from "./fr/index.js";
 export * as gb from "./gb/index.js";
 export * as jp from "./jp/index.js";
+export * as levels from "./level-semantics.js";
 export * as nz from "./nz/index.js";
 export { candidateSystemsForPostcode } from "./postcode-systems.js";
 export * as us from "./us/index.js";

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,GAEpB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAmB,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,GAEpB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,sBAAsB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAmB,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}

package/out/level-semantics.d.ts

@@ -0,0 +1,465 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-locale LEVEL semantics — the fix for "Flr 1 means something different depending on where you
+ *   are" (#1100, the secondary-address epic's second data deliverable). {@link "./us/unit-designator.ts"},
+ *   {@link "./us/floor-designator.ts"}, and {@link "./au/level-designator.ts"} each standardize ONE
+ *   address system's floor/level VOCABULARY — which surface tokens exist ("FL", "L 3", "Ground
+ *   Floor"). This module standardizes the cross-locale ORDINAL SEMANTICS those tokens carry: the fact
+ *   that "1st floor" names the SAME physical storey as "ground floor" in the United States
+ *   (`firstNumberedIsGround: true`) but ONE STOREY ABOVE it in France, Germany, and most of
+ *   continental Europe (`firstNumberedIsGround: false`), where ground already has its own name (RDC,
+ *   EG, PLANTA BAJA, …) and claims ordinal 0 on its own.
+ *
+ *   This is inherently a MULTI-LOCALE module — unlike `us/`, `au/`, `fr/`, … it doesn't belong to one
+ *   address system, so it lives at the codex root and is exported only from the root barrel
+ *   (mirroring `address-system-conventions.ts` and `postcode-systems.ts`, the other cross-system root
+ *   modules). It does not get its own `@mailwoman/codex/<x>` subpath.
+ *
+ *   Two tables do the work:
+ *
+ *   1. {@link LEVEL_DESIGNATORS_BY_FAMILY} — the designator LEXICON per LANGUAGE family (the surface
+ *      vocabulary: FL/FLOOR/LVL/LEVEL, ÉTAGE/ÉT, OG/OBERGESCHOSS, …). Keyed by a bare language tag
+ *      ("en", "fr", "de", …) because the WORDS don't vary by country — American and British English
+ *      both say "floor", "basement", "penthouse".
+ *   2. {@link LEVEL_ORDINAL_CONVENTIONS} — the ORDINAL CONVENTION per full locale ("en-US", "en-GB",
+ *      …), because the NUMBERING varies by country even within one language: American and Canadian
+ *      buildings both call the ground floor "the 1st floor"; British buildings, like the rest of the
+ *      IMDF/continental-European convention locales, do not.
+ *
+ *   {@link levelToOrdinal} composes both: look up the designator's KIND in the locale's language
+ *   family (ground / basement / numbered / fractional / special / fixed), then — for numbered
+ *   designators only — apply the locale's numbering convention. IMDF (Apple's Indoor Mapping Data
+ *   Format) is the schema precedent for encoding a level as a signed integer `ordinal` where ground is
+ *   always 0; this table supplies the locale-aware mapping from a raw (designator, number) pair into
+ *   that same ordinal space.
+ *
+ *   Data is convention encoded from common postal/building usage, not a single postal authority
+ *   publication — level-numbering conventions are cultural, not regulatory, so no Pub-28-style single
+ *   source exists for most of these locales. Retrieved/encoded 2026-07-13, epic #1100.
+ *
+ *   Deliberately-excluded ambiguities (handled by an explicit, documented rounding rule below, never a
+ *   silent guess):
+ *
+ *   - **Spanish PRINCIPAL / ENTRESUELO**: pre-metric Spanish buildings run BAJO (0) → ENTRESUELO
+ *     (~0.5) → PRINCIPAL (1) → PISO 1/2 (2), but the exact offset varies by city and building age.
+ *     ENTRESUELO's true position (0.5) isn't representable as an integer ordinal; it floors to 0
+ *     (grouped with ground) — a documented approximation, not an empirical claim. PRINCIPAL is a
+ *     fixed, always-ordinal-1 designator (it names a specific floor by convention, not by a number the
+ *     caller supplies).
+ *   - **English LOWER GROUND / UPPER GROUND** (UK mixed-use buildings): sit at roughly -0.5 and +0.5
+ *     relative to ground. Both round DOWN (floor): LOWER GROUND → -1 (grouped with the first basement
+ *     level), UPPER GROUND → 0 (grouped with ground). Convention choices, not measurements.
+ *   - **PENTHOUSE / ROOF / ATTIC / DACHGESCHOSS / ÁTICO / ATTICO**: named by relationship to the TOP of
+ *     a SPECIFIC building, not by a fixed distance from ground — there is no locale-independent integer
+ *     to assign. {@link levelToOrdinal} returns `undefined` for this designator kind rather than
+ *     guessing.
+ *   - **Nordic ground-floor vocabulary**: Danish STUEN/STUEETAGE is a well-attested standard term
+ *     (the "st." you see on Danish addresses). Norwegian has no equally standard, universally-agreed
+ *     single word for "ground floor" distinct from "1. etasje" in everyday use; GATEPLAN is included
+ *     here for structural parity with the other Nordic tables but is a lower-confidence, regional
+ *     inclusion — flagged in-line, not asserted as authoritative.
+ *
+ * @see {@link https://register.apple.com/resources/imdf/Level/ IMDF Level — `ordinal` (Apple Indoor Mapping Data Format)}
+ */
+/**
+ * How a level designator's ordinal is derived. See the module header for the rationale behind each non-obvious kind.
+ *
+ * - `"ground"` — always ordinal 0 (RDC, EG, PLANTA BAJA, …).
+ * - `"basement"` — ordinal is the negation of the trailing number, defaulting to 1 when the designator appears bare
+ *   ("Basement" alone → -1, same as "B1").
+ * - `"numbered"` — ordinal depends on the locale's {@link LevelOrdinalConvention} (US/CA/JP-style vs
+ *   continental-European/IMDF-style); requires a number.
+ * - `"fractionalAboveGround"` — conceptually between ground and the first numbered level (mezzanine, entresol/entresuelo,
+ *   upper ground, German Zwischengeschoss); floors to ordinal 0.
+ * - `"fractionalBelowGround"` — conceptually between the first basement level and ground (UK lower ground, Italian
+ *   seminterrato); floors to ordinal -1.
+ * - `"special"` — named by relationship to a SPECIFIC building's top (penthouse, roof, attic); no locale-independent
+ *   ordinal exists. {@link levelToOrdinal} returns `undefined`.
+ * - `"fixedOrdinal"` — a specific named floor with its own fixed ordinal, independent of any number the caller supplies
+ *   (Spanish PRINCIPAL is always ordinal 1).
+ */
+export type LevelDesignatorKind = "ground" | "basement" | "numbered" | "fractionalAboveGround" | "fractionalBelowGround" | "special" | "fixedOrdinal";
+/** One row of a per-language-family level-designator lexicon. */
+export interface LevelDesignatorRow {
+    /** Canonical designator key (the language's native canonical spelling, uppercase). */
+    code: string;
+    /** Human-readable name — the native word plus an English gloss in parentheses. */
+    name: string;
+    /** Recognized surface variants, including the canonical code itself and common ASCII-folded / abbreviated spellings. */
+    variants: readonly string[];
+    /** How this designator maps to an ordinal — see {@link LevelDesignatorKind}. */
+    kind: LevelDesignatorKind;
+    /** True when a secondary number typically follows ("FL 3", "B 2"); false for standalone designators ("EG", "RDC"). */
+    requiresNumber: boolean;
+    /**
+     * Only present when `kind` is `"fixedOrdinal"` — the designator's own fixed ordinal, independent of any passed
+     * number.
+     */
+    fixedOrdinal?: number;
+}
+/**
+ * English (American, British, Canadian, Australian, …) floor/level vocabulary. This is the GENERIC English lexicon for
+ * the ordinal-semantics table; it doesn't replace the more detailed per-system lexicons in
+ * {@link "./us/floor-designator.ts"} (USPS Pub-28 C2) or {@link "./au/level-designator.ts"} (AS 4590.1 / AMAS) — those
+ * drive span-proposer/synthesis vocabulary for their own address system. This table exists to answer a narrower
+ * question for ANY English-speaking locale: given a designator + number, what ordinal does it name.
+ */
+export declare const EN_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "FLOOR";
+    readonly name: "Floor";
+    readonly variants: readonly ["FLOOR", "FL", "FLR", "LEVEL", "LVL"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "BASEMENT";
+    readonly name: "Basement";
+    readonly variants: readonly ["BASEMENT", "BSMT", "B"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "PENTHOUSE";
+    readonly name: "Penthouse";
+    readonly variants: readonly ["PENTHOUSE", "PH"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "GROUND";
+    readonly name: "Ground";
+    readonly variants: readonly ["GROUND", "G", "GROUND FLOOR", "GF"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "LOWER GROUND";
+    readonly name: "Lower Ground";
+    readonly variants: readonly ["LOWER GROUND", "LG"];
+    readonly kind: "fractionalBelowGround";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "UPPER GROUND";
+    readonly name: "Upper Ground";
+    readonly variants: readonly ["UPPER GROUND", "UG"];
+    readonly kind: "fractionalAboveGround";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "MEZZANINE";
+    readonly name: "Mezzanine";
+    readonly variants: readonly ["MEZZANINE", "MEZZ", "M"];
+    readonly kind: "fractionalAboveGround";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "ROOF";
+    readonly name: "Roof";
+    readonly variants: readonly ["ROOF", "RF"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}];
+/** French (France, and — for the vocabulary, not the numbering convention — Francophone Canada) floor/level vocabulary. */
+export declare const FR_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "ÉTAGE";
+    readonly name: "Étage (Floor)";
+    readonly variants: readonly ["ÉTAGE", "ETAGE", "ÉT", "ET"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "RDC";
+    readonly name: "Rez-de-chaussée (Ground floor)";
+    readonly variants: readonly ["RDC", "REZ-DE-CHAUSSÉE", "REZ-DE-CHAUSSEE", "REZ DE CHAUSSEE"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "SOUS-SOL";
+    readonly name: "Sous-sol (Basement)";
+    readonly variants: readonly ["SOUS-SOL", "SOUS SOL", "SS"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "ENTRESOL";
+    readonly name: "Entresol (Mezzanine)";
+    readonly variants: readonly ["ENTRESOL"];
+    readonly kind: "fractionalAboveGround";
+    readonly requiresNumber: false;
+}];
+/** German floor/level vocabulary (the -geschoss family). */
+export declare const DE_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "OBERGESCHOSS";
+    readonly name: "Obergeschoss (Upper floor)";
+    readonly variants: readonly ["OBERGESCHOSS", "OG"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "ERDGESCHOSS";
+    readonly name: "Erdgeschoss (Ground floor)";
+    readonly variants: readonly ["ERDGESCHOSS", "EG"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "UNTERGESCHOSS";
+    readonly name: "Untergeschoss (Basement)";
+    readonly variants: readonly ["UNTERGESCHOSS", "UG"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "DACHGESCHOSS";
+    readonly name: "Dachgeschoss (Attic/roof floor)";
+    readonly variants: readonly ["DACHGESCHOSS", "DG"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "ZWISCHENGESCHOSS";
+    readonly name: "Zwischengeschoss (Mezzanine)";
+    readonly variants: readonly ["ZWISCHENGESCHOSS", "ZG"];
+    readonly kind: "fractionalAboveGround";
+    readonly requiresNumber: false;
+}];
+/**
+ * Spanish floor/level vocabulary. PRINCIPAL and ENTRESUELO offsets vary by city and building age (see the module
+ * header) — encoded here as a single convention, not an empirical universal.
+ */
+export declare const ES_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "PLANTA";
+    readonly name: "Planta/Piso (Floor)";
+    readonly variants: readonly ["PLANTA", "PISO"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "PLANTA BAJA";
+    readonly name: "Planta Baja (Ground floor)";
+    readonly variants: readonly ["PLANTA BAJA", "BAJO", "PB"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "ENTRESUELO";
+    readonly name: "Entresuelo (Mezzanine)";
+    readonly variants: readonly ["ENTRESUELO"];
+    readonly kind: "fractionalAboveGround";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "PRINCIPAL";
+    readonly name: "Principal";
+    readonly variants: readonly ["PRINCIPAL"];
+    readonly kind: "fixedOrdinal";
+    readonly requiresNumber: false;
+    readonly fixedOrdinal: 1;
+}, {
+    readonly code: "SÓTANO";
+    readonly name: "Sótano (Basement)";
+    readonly variants: readonly ["SÓTANO", "SOTANO"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "ÁTICO";
+    readonly name: "Ático (Attic/penthouse)";
+    readonly variants: readonly ["ÁTICO", "ATICO"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}];
+/** Italian floor/level vocabulary. */
+export declare const IT_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "PIANO";
+    readonly name: "Piano (Floor)";
+    readonly variants: readonly ["PIANO"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "PIANO TERRA";
+    readonly name: "Piano Terra (Ground floor)";
+    readonly variants: readonly ["PIANO TERRA", "PT"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "SEMINTERRATO";
+    readonly name: "Seminterrato (Semi-basement)";
+    readonly variants: readonly ["SEMINTERRATO"];
+    readonly kind: "fractionalBelowGround";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "ATTICO";
+    readonly name: "Attico (Attic/penthouse)";
+    readonly variants: readonly ["ATTICO"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}];
+/** Portuguese floor/level vocabulary. */
+export declare const PT_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "ANDAR";
+    readonly name: "Andar (Floor)";
+    readonly variants: readonly ["ANDAR"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "RÉS-DO-CHÃO";
+    readonly name: "Rés-do-chão (Ground floor)";
+    readonly variants: readonly ["RÉS-DO-CHÃO", "RES-DO-CHAO", "RC"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "CAVE";
+    readonly name: "Cave (Basement)";
+    readonly variants: readonly ["CAVE"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}];
+/** Dutch floor/level vocabulary. */
+export declare const NL_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "VERDIEPING";
+    readonly name: "Verdieping (Floor)";
+    readonly variants: readonly ["VERDIEPING", "VERD"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "BEGANE GROND";
+    readonly name: "Begane Grond (Ground floor)";
+    readonly variants: readonly ["BEGANE GROND", "BG"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "KELDER";
+    readonly name: "Kelder (Basement)";
+    readonly variants: readonly ["KELDER"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}];
+/**
+ * Japanese (and generic CJK numeral+letter) floor/level vocabulary. Japanese addresses write the numbered floor as a
+ * trailing "F" suffix on the number ("2F", "地下1F"/"B1F") or the kanji "階" ("2階"); there is no distinct bare word for
+ * "ground floor" the way RDC/EG/PLANTA BAJA exist in Europe — "1F"/"1階" already IS ground (handled by the `"numbered"`
+ * kind + the ja-JP `firstNumberedIsGround: true` convention, not a separate `"ground"` row). "B" (and "地下", literally
+ * "underground") name the basement count the same way English "B1" does.
+ */
+export declare const JA_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "F";
+    readonly name: "階 (Floor)";
+    readonly variants: readonly ["F", "階"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "B";
+    readonly name: "地下 (Basement)";
+    readonly variants: readonly ["B", "地下"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "RF";
+    readonly name: "屋上 (Rooftop)";
+    readonly variants: readonly ["RF", "屋上", "ROOFTOP"];
+    readonly kind: "special";
+    readonly requiresNumber: false;
+}];
+/** Swedish floor/level vocabulary. */
+export declare const SV_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "VÅNING";
+    readonly name: "Våning (Floor)";
+    readonly variants: readonly ["VÅNING", "VANING"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "BOTTENVÅNING";
+    readonly name: "Bottenvåning (Ground floor)";
+    readonly variants: readonly ["BOTTENVÅNING", "BOTTENVANING", "BV"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "KÄLLARE";
+    readonly name: "Källare (Basement)";
+    readonly variants: readonly ["KÄLLARE", "KALLARE"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}];
+/**
+ * Norwegian floor/level vocabulary. GATEPLAN ("street level") is a lower-confidence, regional inclusion for the
+ * ground-floor row — see the module header's Nordic-vocabulary caveat.
+ */
+export declare const NO_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "ETASJE";
+    readonly name: "Etasje (Floor)";
+    readonly variants: readonly ["ETASJE"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "GATEPLAN";
+    readonly name: "Gateplan (Street/ground level)";
+    readonly variants: readonly ["GATEPLAN"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "KJELLER";
+    readonly name: "Kjeller (Basement)";
+    readonly variants: readonly ["KJELLER"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}];
+/** Danish floor/level vocabulary. STUEN/STUEETAGE ("st.") is the standard ground-floor term seen on Danish addresses. */
+export declare const DA_LEVEL_DESIGNATORS: readonly [{
+    readonly code: "ETAGE";
+    readonly name: "Etage (Floor)";
+    readonly variants: readonly ["ETAGE"];
+    readonly kind: "numbered";
+    readonly requiresNumber: true;
+}, {
+    readonly code: "STUEN";
+    readonly name: "Stuen/Stueetage (Ground floor)";
+    readonly variants: readonly ["STUEN", "STUEETAGE", "ST"];
+    readonly kind: "ground";
+    readonly requiresNumber: false;
+}, {
+    readonly code: "KÆLDER";
+    readonly name: "Kælder (Basement)";
+    readonly variants: readonly ["KÆLDER", "KAELDER"];
+    readonly kind: "basement";
+    readonly requiresNumber: true;
+}];
+/** A bare language-family tag — the key into {@link LEVEL_DESIGNATORS_BY_FAMILY}. */
+export type LevelLocaleFamily = "en" | "fr" | "de" | "es" | "it" | "pt" | "nl" | "ja" | "sv" | "no" | "da";
+/** Every language family's level-designator lexicon, keyed by bare language tag. */
+export declare const LEVEL_DESIGNATORS_BY_FAMILY: Readonly<Record<LevelLocaleFamily, readonly LevelDesignatorRow[]>>;
+/**
+ * The locale's level-numbering convention: does the FIRST numbered level ("1st floor", "1F", "étage 1", …) coincide
+ * with ground (ordinal 0), or sit one storey above it?
+ */
+export interface LevelOrdinalConvention {
+    /**
+     * True for the US/Canada/Japan-style convention, where the first numbered level IS ground ("1st floor" = ground floor
+     * = ordinal 0, so ordinal = number - 1). False for the continental-European / IMDF-style convention, where ground has
+     * its own designator (RDC, EG, PLANTA BAJA, …) and the first NUMBERED level sits one storey above it (ordinal =
+     * number) — also the convention in the UK.
+     */
+    readonly firstNumberedIsGround: boolean;
+}
+/**
+ * Per-FULL-LOCALE ordinal convention overrides. Keyed by full locale (not bare language family) because English splits
+ * by country even though the vocabulary doesn't: American and Canadian buildings number the ground floor "1"; British
+ * buildings do not. "CA" (English or French) buckets with the US/Japan convention per real-world North American
+ * building-code practice, though individual Quebec buildings can and do vary.
+ */
+export declare const LEVEL_ORDINAL_CONVENTIONS: Readonly<Record<string, LevelOrdinalConvention>>;
+/**
+ * Look up a level designator (by canonical code, abbreviation, or any recognized variant) within a locale's language
+ * family. Case-insensitive. Returns `undefined` when the locale's family is unknown to this module, or the token isn't
+ * a recognized designator in that family.
+ */
+export declare function lookupLevelDesignator(designator: string, locale: string): LevelDesignatorRow | undefined;
+/** True when `input` is a recognized level designator (case-insensitive) in `locale`'s language family. */
+export declare function isLevelDesignatorToken(input: unknown, locale: string): boolean;
+/**
+ * Map a (designator, number) pair to an IMDF-style signed integer ordinal, given the semantics of `locale`. Ground is
+ * always 0. Returns `undefined` when:
+ *
+ * - `locale`'s language family has no lexicon in this module,
+ * - `designator` isn't a recognized token in that family,
+ * - The designator is `"special"` (penthouse/roof/attic — no locale-independent ordinal exists), or
+ * - The designator is `"numbered"` but either `number` is missing or the locale has no resolvable ordinal convention (a
+ *   bare "en" locale, for example).
+ *
+ * @example
+ * 	levelToOrdinal("FL", 1, "en-US") // → 0 (US: 1st floor IS ground)
+ * 	levelToOrdinal("étage", 1, "fr-FR") // → 1 (FR: 1st étage is one storey above ground)
+ * 	levelToOrdinal("EG", undefined, "de-DE") // → 0 (ground, number ignored)
+ * 	levelToOrdinal("B", 1, "en-US") // → -1 (basement 1)
+ * 	levelToOrdinal("F", 1, "ja-JP") // → 0 (JP: 1F IS ground)
+ * 	levelToOrdinal("B", 1, "ja-JP") // → -1 (JP: B1F)
+ */
+export declare function levelToOrdinal(designator: string, number: number | undefined, locale: string): number | undefined;
+//# sourceMappingURL=level-semantics.d.ts.map

package/out/level-semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level-semantics.d.ts","sourceRoot":"","sources":["../level-semantics.ts"],"names":[],"mappings":"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"}