@openmrs/esm-utils 10.0.1-pre.5136 → 10.0.1-pre.5147

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
-[0] Successfully compiled: 14 files with swc (185.86ms)
+[0] Successfully compiled: 15 files with swc (266.47ms)
 [0] swc --strip-leading-paths src -d dist exited with code 0
 [1] tsc --project tsconfig.build.json exited with code 0

package/dist/get-locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-locale.d.ts","sourceRoot":"","sources":["../src/get-locale.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,SAAS,WASxB"}
+{"version":3,"file":"get-locale.d.ts","sourceRoot":"","sources":["../src/get-locale.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,SAAS,WAWxB"}

package/dist/get-locale.js

@@ -1,9 +1,12 @@
+import { toLanguageTag } from "./language-tag.js";
 /**
  * Returns the current locale of the application.
  * @returns string
  */ export function getLocale() {
-    let language = window.i18next.language;
-    language = language.replaceAll('_', '-'); // just in case
+    // i18next detects the language from the `lang` attribute, a `?lang=` parameter, localStorage or
+    // the browser, none of which is guaranteed to be a BCP 47 tag, so normalize before returning.
+    const detected = window.i18next.language;
+    let language = toLanguageTag(detected) ?? detected;
     // Hack for `ht` until all browsers update their unicode support with ht to fr mapping.
     // See https://unicode-org.atlassian.net/browse/CLDR-14956
     if (language === 'ht') {

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './age-helpers';
 export * from './dates';
 export * from './get-locale';
 export * from './is-online';
+export * from './language-tag';
 export * from './match-locale';
 export * from './patient-helpers';
 export * from './shallowEqual';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./age-helpers.js";
 export * from "./dates/index.js";
 export * from "./get-locale.js";
 export * from "./is-online.js";
+export * from "./language-tag.js";
 export * from "./match-locale.js";
 export * from "./patient-helpers.js";
 export * from "./shallowEqual.js";

package/dist/language-tag.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Converts an OpenMRS locale identifier into a canonical BCP 47 language tag.
+ *
+ * OpenMRS locale identifiers are not always language tags. User properties such as
+ * `defaultLocale` store Java's `Locale#toString()` form (`en_US`, `sw_KE`) verbatim, some backends
+ * serialize session locales the same way, and some installs configure POSIX-style variants
+ * (`uz@Latn`). The `Intl` constructors throw `RangeError` rather than degrading when handed any of
+ * them, so convert before passing an OpenMRS locale to `Intl`.
+ *
+ * Both `_` and `@` are treated as subtag separators, which covers the `@Latn` script modifier.
+ * Other POSIX modifiers have no BCP 47 equivalent and parse as whatever their length implies
+ * (`de@euro` becomes the script subtag `de-Euro`), so they are converted rather than rejected.
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`. Locale data reaching this function
+ *   comes from the REST session and from configuration, so anything that is not a string is
+ *   treated as an unresolvable locale rather than an error.
+ * @returns The canonical language tag, or `undefined` if `locale` is not a structurally valid tag.
+ *
+ * @example
+ * toLanguageTag('sw_KE'); // => 'sw-KE'
+ * toLanguageTag('uz@Latn'); // => 'uz-Latn'
+ * toLanguageTag('en_us'); // => 'en-US'
+ * toLanguageTag('not a locale'); // => undefined
+ */
+export declare function toLanguageTag(locale: string | null | undefined): string | undefined;
+/**
+ * Returns the name of a locale as written in that locale, so `fr` becomes "français" and `sw_KE`
+ * becomes "Kiswahili (Kenya)". Falls back to the identifier itself for anything `Intl` cannot
+ * resolve, so the result is always safe to render.
+ *
+ * The name is CLDR's middle-of-sentence form. When presenting it as a standalone label, capitalize
+ * only the first character: lowercasing the remainder corrupts names carrying internal capitals,
+ * turning "American English" into "American english".
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`.
+ * @returns The locale's name in its own language, `locale` itself if it cannot be resolved, or an
+ *   empty string if no locale was given.
+ *
+ * @example
+ * getLocaleDisplayName('fr'); // => 'français'
+ * getLocaleDisplayName('sw_KE'); // => 'Kiswahili (Kenya)'
+ */
+export declare function getLocaleDisplayName(locale: string | null | undefined): string;
+//# sourceMappingURL=language-tag.d.ts.map

package/dist/language-tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-tag.d.ts","sourceRoot":"","sources":["../src/language-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAUnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAe9E"}

package/dist/language-tag.js

@@ -0,0 +1,67 @@
+/**
+ * Converts an OpenMRS locale identifier into a canonical BCP 47 language tag.
+ *
+ * OpenMRS locale identifiers are not always language tags. User properties such as
+ * `defaultLocale` store Java's `Locale#toString()` form (`en_US`, `sw_KE`) verbatim, some backends
+ * serialize session locales the same way, and some installs configure POSIX-style variants
+ * (`uz@Latn`). The `Intl` constructors throw `RangeError` rather than degrading when handed any of
+ * them, so convert before passing an OpenMRS locale to `Intl`.
+ *
+ * Both `_` and `@` are treated as subtag separators, which covers the `@Latn` script modifier.
+ * Other POSIX modifiers have no BCP 47 equivalent and parse as whatever their length implies
+ * (`de@euro` becomes the script subtag `de-Euro`), so they are converted rather than rejected.
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`. Locale data reaching this function
+ *   comes from the REST session and from configuration, so anything that is not a string is
+ *   treated as an unresolvable locale rather than an error.
+ * @returns The canonical language tag, or `undefined` if `locale` is not a structurally valid tag.
+ *
+ * @example
+ * toLanguageTag('sw_KE'); // => 'sw-KE'
+ * toLanguageTag('uz@Latn'); // => 'uz-Latn'
+ * toLanguageTag('en_us'); // => 'en-US'
+ * toLanguageTag('not a locale'); // => undefined
+ */ export function toLanguageTag(locale) {
+    if (typeof locale !== 'string' || locale.trim().length === 0) {
+        return undefined;
+    }
+    try {
+        return new Intl.Locale(locale.replace(/[_@]/g, '-')).toString();
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Returns the name of a locale as written in that locale, so `fr` becomes "français" and `sw_KE`
+ * becomes "Kiswahili (Kenya)". Falls back to the identifier itself for anything `Intl` cannot
+ * resolve, so the result is always safe to render.
+ *
+ * The name is CLDR's middle-of-sentence form. When presenting it as a standalone label, capitalize
+ * only the first character: lowercasing the remainder corrupts names carrying internal capitals,
+ * turning "American English" into "American english".
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`.
+ * @returns The locale's name in its own language, `locale` itself if it cannot be resolved, or an
+ *   empty string if no locale was given.
+ *
+ * @example
+ * getLocaleDisplayName('fr'); // => 'français'
+ * getLocaleDisplayName('sw_KE'); // => 'Kiswahili (Kenya)'
+ */ export function getLocaleDisplayName(locale) {
+    const identifier = locale ?? '';
+    const languageTag = toLanguageTag(identifier);
+    if (!languageTag) {
+        return identifier;
+    }
+    try {
+        return new Intl.DisplayNames([
+            languageTag
+        ], {
+            type: 'language'
+        }).of(languageTag) ?? identifier;
+    } catch  {
+        // `Intl.DisplayNames` validates independently of `Intl.Locale` and rejects tags carrying
+        // extension or private-use subtags, such as `en-u-ca-gregory`.
+        return identifier;
+    }
+}

package/dist/match-locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"match-locale.d.ts","sourceRoot":"","sources":["../src/match-locale.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CA6DpB"}
+{"version":3,"file":"match-locale.d.ts","sourceRoot":"","sources":["../src/match-locale.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CA6DpB"}

package/dist/match-locale.js

@@ -1,19 +1,4 @@
-/**
- * Returns a canonical BCP 47 representation of `tag`, or `undefined` if it is not a
- * structurally valid tag. Underscores are accepted as a separator and normalized to
- * hyphens before canonicalization to accommodate locale strings that originate from
- * Java-style identifiers (e.g. `en_GB`).
- */ function canonicalize(tag) {
-    if (typeof tag !== 'string' || tag.trim().length === 0) {
-        return undefined;
-    }
-    const normalized = tag.replaceAll('_', '-');
-    try {
-        return new Intl.Locale(normalized).toString();
-    } catch  {
-        return undefined;
-    }
-}
+import { toLanguageTag } from "./language-tag.js";
 /**
  * Resolves a requested locale against a list of available locales using the
  * BCP 47 lookup algorithm (RFC 4647, §3.4).
@@ -49,14 +34,14 @@
     if (requested == null) {
         return fallback;
     }
-    const requestedCanonical = canonicalize(requested);
+    const requestedCanonical = toLanguageTag(requested);
     if (!requestedCanonical) {
         console.warn(`matchLocale: invalid requested locale tag: ${JSON.stringify(requested)}`);
         return fallback;
     }
     const pool = [];
     for (const entry of available){
-        const canonical = canonicalize(entry);
+        const canonical = toLanguageTag(entry);
         if (!canonical) {
             console.warn(`matchLocale: skipping invalid available locale tag: ${JSON.stringify(entry)}`);
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-utils",
-  "version": "10.0.1-pre.5136",
+  "version": "10.0.1-pre.5147",
   "license": "MPL-2.0",
   "description": "Helper utilities for OpenMRS",
   "type": "module",
@@ -57,13 +57,13 @@
     "semver": "^7.7.3"
   },
   "peerDependencies": {
-    "@openmrs/esm-globals": "^10.0.1-pre.5136",
+    "@openmrs/esm-globals": "^10.0.1-pre.5147",
     "dayjs": "1.x",
     "i18next": "25.x",
     "rxjs": "6.x"
   },
   "devDependencies": {
-    "@openmrs/esm-globals": "10.0.1-pre.5136",
+    "@openmrs/esm-globals": "10.0.1-pre.5147",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@types/lodash-es": "^4.17.12",

package/src/get-locale.ts

@@ -1,10 +1,14 @@
+import { toLanguageTag } from './language-tag';
+
 /**
  * Returns the current locale of the application.
  * @returns string
  */
 export function getLocale() {
-  let language = window.i18next.language;
-  language = language.replaceAll('_', '-'); // just in case
+  // i18next detects the language from the `lang` attribute, a `?lang=` parameter, localStorage or
+  // the browser, none of which is guaranteed to be a BCP 47 tag, so normalize before returning.
+  const detected = window.i18next.language;
+  let language = toLanguageTag(detected) ?? detected;
   // Hack for `ht` until all browsers update their unicode support with ht to fr mapping.
   // See https://unicode-org.atlassian.net/browse/CLDR-14956
   if (language === 'ht') {

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './age-helpers';
 export * from './dates';
 export * from './get-locale';
 export * from './is-online';
+export * from './language-tag';
 export * from './match-locale';
 export * from './patient-helpers';
 export * from './shallowEqual';

package/src/language-tag.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { getLocaleDisplayName, toLanguageTag } from './language-tag';
+
+describe('toLanguageTag', () => {
+  it.each([
+    ['en', 'en'],
+    // The REST session reports Java `Locale#toString()` values, which are not language tags.
+    ['en_US', 'en-US'],
+    ['sw_KE', 'sw-KE'],
+    ['uz@Latn', 'uz-Latn'],
+    // Canonicalization also fixes subtag casing.
+    ['en_us', 'en-US'],
+    ['ZH-hant-tw', 'zh-Hant-TW'],
+  ])('converts %s to %s', (locale, expected) => {
+    expect(toLanguageTag(locale)).toBe(expected);
+  });
+
+  it.each([['not a locale'], ['!!!'], ['']])('returns undefined for %j', (locale) => {
+    expect(toLanguageTag(locale)).toBeUndefined();
+  });
+
+  it('returns undefined for a missing locale rather than throwing', () => {
+    expect(toLanguageTag(null)).toBeUndefined();
+    expect(toLanguageTag(undefined)).toBeUndefined();
+  });
+});
+
+describe('getLocaleDisplayName', () => {
+  it.each([
+    ['en', 'English'],
+    ['fr', 'français'],
+    ['en_US', 'American English'],
+    ['sw_KE', 'Kiswahili (Kenya)'],
+    ['pt_BR', 'português (Brasil)'],
+  ])('renders %s as %s', (locale, expected) => {
+    expect(getLocaleDisplayName(locale)).toBe(expected);
+  });
+
+  it('resolves a POSIX script modifier to a name rather than the raw identifier', () => {
+    // Asserted loosely on purpose. The script name is engine-specific: Node renders `uz@Latn` as
+    // "o‘zbek (lotin)" and Chrome as "O‘zbek (Latn)", so pinning either would assert a string half
+    // the runtimes never produce. `toLanguageTag` covers the conversion itself exactly.
+    const name = getLocaleDisplayName('uz@Latn');
+
+    expect(name).not.toBe('uz@Latn');
+    expect(name.toLowerCase()).toContain('zbek');
+  });
+
+  it('falls back to the identifier when the locale is not a valid tag', () => {
+    expect(getLocaleDisplayName('not a locale at all')).toBe('not a locale at all');
+  });
+
+  it('falls back to the identifier for a tag `Intl.DisplayNames` rejects', () => {
+    // `Intl.Locale` accepts extension subtags but `Intl.DisplayNames#of` throws on them.
+    expect(getLocaleDisplayName('en-u-ca-gregory')).toBe('en-u-ca-gregory');
+  });
+
+  it('returns an empty string when no locale is given', () => {
+    expect(getLocaleDisplayName(null)).toBe('');
+    expect(getLocaleDisplayName(undefined)).toBe('');
+  });
+});

package/src/language-tag.ts

@@ -0,0 +1,69 @@
+/**
+ * Converts an OpenMRS locale identifier into a canonical BCP 47 language tag.
+ *
+ * OpenMRS locale identifiers are not always language tags. User properties such as
+ * `defaultLocale` store Java's `Locale#toString()` form (`en_US`, `sw_KE`) verbatim, some backends
+ * serialize session locales the same way, and some installs configure POSIX-style variants
+ * (`uz@Latn`). The `Intl` constructors throw `RangeError` rather than degrading when handed any of
+ * them, so convert before passing an OpenMRS locale to `Intl`.
+ *
+ * Both `_` and `@` are treated as subtag separators, which covers the `@Latn` script modifier.
+ * Other POSIX modifiers have no BCP 47 equivalent and parse as whatever their length implies
+ * (`de@euro` becomes the script subtag `de-Euro`), so they are converted rather than rejected.
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`. Locale data reaching this function
+ *   comes from the REST session and from configuration, so anything that is not a string is
+ *   treated as an unresolvable locale rather than an error.
+ * @returns The canonical language tag, or `undefined` if `locale` is not a structurally valid tag.
+ *
+ * @example
+ * toLanguageTag('sw_KE'); // => 'sw-KE'
+ * toLanguageTag('uz@Latn'); // => 'uz-Latn'
+ * toLanguageTag('en_us'); // => 'en-US'
+ * toLanguageTag('not a locale'); // => undefined
+ */
+export function toLanguageTag(locale: string | null | undefined): string | undefined {
+  if (typeof locale !== 'string' || locale.trim().length === 0) {
+    return undefined;
+  }
+
+  try {
+    return new Intl.Locale(locale.replace(/[_@]/g, '-')).toString();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Returns the name of a locale as written in that locale, so `fr` becomes "français" and `sw_KE`
+ * becomes "Kiswahili (Kenya)". Falls back to the identifier itself for anything `Intl` cannot
+ * resolve, so the result is always safe to render.
+ *
+ * The name is CLDR's middle-of-sentence form. When presenting it as a standalone label, capitalize
+ * only the first character: lowercasing the remainder corrupts names carrying internal capitals,
+ * turning "American English" into "American english".
+ *
+ * @param locale An OpenMRS locale identifier, e.g. `sw_KE`.
+ * @returns The locale's name in its own language, `locale` itself if it cannot be resolved, or an
+ *   empty string if no locale was given.
+ *
+ * @example
+ * getLocaleDisplayName('fr'); // => 'français'
+ * getLocaleDisplayName('sw_KE'); // => 'Kiswahili (Kenya)'
+ */
+export function getLocaleDisplayName(locale: string | null | undefined): string {
+  const identifier = locale ?? '';
+  const languageTag = toLanguageTag(identifier);
+
+  if (!languageTag) {
+    return identifier;
+  }
+
+  try {
+    return new Intl.DisplayNames([languageTag], { type: 'language' }).of(languageTag) ?? identifier;
+  } catch {
+    // `Intl.DisplayNames` validates independently of `Intl.Locale` and rejects tags carrying
+    // extension or private-use subtags, such as `en-u-ca-gregory`.
+    return identifier;
+  }
+}

package/src/match-locale.test.ts

@@ -54,6 +54,12 @@ describe('matchLocale', () => {
     it('canonicalizes script casing for matching (Latn vs latn)', () => {
       expect(matchLocale('sr-latn-rs', ['sr-Latn'])).toBe('sr-Latn');
     });
+
+    it('treats a POSIX script modifier as a script subtag', () => {
+      // `uz@Latn` is the form OpenMRS ships translations under, on both sides of the comparison.
+      expect(matchLocale('uz@Latn', ['uz@Latn'])).toBe('uz@Latn');
+      expect(matchLocale('uz@Latn', ['uz-Latn'])).toBe('uz-Latn');
+    });
   });
 
   describe('truncation', () => {

package/src/match-locale.ts

@@ -1,22 +1,4 @@
-/**
- * Returns a canonical BCP 47 representation of `tag`, or `undefined` if it is not a
- * structurally valid tag. Underscores are accepted as a separator and normalized to
- * hyphens before canonicalization to accommodate locale strings that originate from
- * Java-style identifiers (e.g. `en_GB`).
- */
-function canonicalize(tag: string): string | undefined {
-  if (typeof tag !== 'string' || tag.trim().length === 0) {
-    return undefined;
-  }
-
-  const normalized = tag.replaceAll('_', '-');
-
-  try {
-    return new Intl.Locale(normalized).toString();
-  } catch {
-    return undefined;
-  }
-}
+import { toLanguageTag } from './language-tag';
 
 /**
  * Resolves a requested locale against a list of available locales using the
@@ -59,7 +41,7 @@ export function matchLocale(
     return fallback;
   }
 
-  const requestedCanonical = canonicalize(requested);
+  const requestedCanonical = toLanguageTag(requested);
   if (!requestedCanonical) {
     console.warn(`matchLocale: invalid requested locale tag: ${JSON.stringify(requested)}`);
     return fallback;
@@ -67,7 +49,7 @@ export function matchLocale(
 
   const pool: Array<{ canonical: string; original: string }> = [];
   for (const entry of available) {
-    const canonical = canonicalize(entry);
+    const canonical = toLanguageTag(entry);
     if (!canonical) {
       console.warn(`matchLocale: skipping invalid available locale tag: ${JSON.stringify(entry)}`);
       continue;