@shoelace-style/localize 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.2.0
+
+- Added `dir()` method to return the target element's directionality
+- Added `lang()` method to return the target element's language
+
+## 2.1.3
+
+- Renamed `updateLocalizedTerms()` to `update()` (forgive me SemVer, but nobody was using this I promise)
+
+## 2.1.2
+
+- Removed all dependencies
+
 ## 2.1.1
 
 - Change import to ensure only types get used

package/README.md

@@ -1,6 +1,6 @@
 # Shoelace: Localize
 
-This micro library does not aim to replicate a full-blown localization tool. For that, you should use something like [i18next](https://www.i18next.com/). What this library _does_ do is provide a lightweight, framework-agnostic mechanism for sharing and applying translations across one or more custom elements in a component library.
+This zero-dependency micro library does not aim to replicate a full-blown localization tool. For that, you should use something like [i18next](https://www.i18next.com/). What this library _does_ do is provide a lightweight, framework-agnostic mechanism for sharing and applying translations across one or more custom elements in a component library.
 
 Included are methods for translating terms, dates, currencies, and numbers and a [Reactive Controller](https://lit.dev/docs/composition/controllers/) that can be used as a mixin in Lit and other supportive component authoring libraries.
 
@@ -185,6 +185,9 @@ export class MyElement extends LitElement {
 
       <!-- Number/currency -->
       ${this.localize.number(1000, { style: 'currency', currency: 'USD'})}
+
+      <!-- Determining directionality, e.g. 'ltr' or 'rtl' -->
+      ${this.localize.dir()}
     `;
   }
 }
@@ -193,7 +196,8 @@ export class MyElement extends LitElement {
 ## Advantages
 
 - Extremely lightweight
-	- ~2.5 KB compared to ~33 KB for i18next (both without translations/minifications)
+  - Zero dependencies
+	- Version 2.1 measures 726 bytes (yes, _bytes_) after minify + gzip
 - Uses existing platform features
 - Supports simple terms, plurals, and complex translations
 	- Fun fact: some languages have [six plural forms](https://lingohub.com/blog/2019/02/pluralization) and this will support that

package/dist/index.d.ts

@@ -11,12 +11,14 @@ export declare function term<K extends keyof Translation>(lang: string, key: K,
 export declare function date(lang: string, dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions): string;
 export declare function number(lang: string, numberToFormat: number | string, options?: Intl.NumberFormatOptions): string;
 export declare function relativeTime(lang: string, value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
-export declare function updateLocalizedTerms(): void;
+export declare function update(): void;
 export declare class LocalizeController implements ReactiveController {
     host: ReactiveControllerHost & HTMLElement;
     constructor(host: ReactiveControllerHost & HTMLElement);
     hostConnected(): void;
     hostDisconnected(): void;
+    dir(): string;
+    lang(): string;
     term<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>): any;
     date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions): string;
     number(numberToFormat: number | string, options?: Intl.NumberFormatOptions): string;

package/dist/index.js

@@ -1,6 +1,7 @@
 const connectedElements = new Set();
-const documentElementObserver = new MutationObserver(updateLocalizedTerms);
+const documentElementObserver = new MutationObserver(update);
 const translations = new Map();
+let documentDirection = document.documentElement.dir || 'ltr';
 let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback;
 documentElementObserver.observe(document.documentElement, {
@@ -15,7 +16,7 @@ export function registerTranslation(...translation) {
             fallback = t;
         }
     });
-    updateLocalizedTerms();
+    update();
 }
 export function term(lang, key, ...args) {
     const code = lang.toLowerCase().slice(0, 2);
@@ -52,7 +53,8 @@ export function number(lang, numberToFormat, options) {
 export function relativeTime(lang, value, unit, options) {
     return new Intl.RelativeTimeFormat(lang, options).format(value, unit);
 }
-export function updateLocalizedTerms() {
+export function update() {
+    documentDirection = document.documentElement.dir || 'ltr';
     documentLanguage = document.documentElement.lang || navigator.language;
     [...connectedElements.keys()].map((el) => {
         if (typeof el.requestUpdate === 'function') {
@@ -71,6 +73,12 @@ export class LocalizeController {
     hostDisconnected() {
         connectedElements.delete(this.host);
     }
+    dir() {
+        return `${this.host.dir || documentDirection}`.toLowerCase();
+    }
+    lang() {
+        return `${this.host.lang || documentLanguage}`.toLowerCase();
+    }
     term(key, ...args) {
         return term(this.host.lang || documentLanguage, key, ...args);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoelace-style/localize",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "A micro library for localizing custom elements using Lit's Reactive Controller model.",
   "main": "/dist/index.js",
   "module": "/dist/index.js",
@@ -34,9 +34,7 @@
   "homepage": "https://github.com/shoelace-style/localize#readme",
   "devDependencies": {
     "del": "^6.0.0",
+    "lit": "^2.0.2",
     "typescript": "^4.4.3"
-  },
-  "dependencies": {
-    "lit": "^2.0.2"
   }
 }

package/src/index.ts

@@ -10,8 +10,9 @@ export interface Translation {
 }
 
 const connectedElements = new Set<HTMLElement>();
-const documentElementObserver = new MutationObserver(updateLocalizedTerms);
+const documentElementObserver = new MutationObserver(update);
 const translations: Map<string, Translation> = new Map();
+let documentDirection = document.documentElement.dir || 'ltr';
 let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback: Translation;
 
@@ -35,7 +36,7 @@ export function registerTranslation(...translation: Translation[]) {
     }
   });
 
-  updateLocalizedTerms();
+  update();
 }
 
 //
@@ -97,9 +98,10 @@ export function relativeTime(
 }
 
 //
-// Updates the locale for all localized elements that are currently connected
+// Updates all localized elements that are currently connected
 //
-export function updateLocalizedTerms() {
+export function update() {
+  documentDirection = document.documentElement.dir || 'ltr';
   documentLanguage = document.documentElement.lang || navigator.language;
 
   [...connectedElements.keys()].map((el: LitElement) => {
@@ -143,18 +145,38 @@ export class LocalizeController implements ReactiveController {
     connectedElements.delete(this.host);
   }
 
+  /**
+   * Gets the host element's directionality as determined by the `dir` attribute. The return value is transformed to
+   * lowercase.
+   */
+  dir() {
+    return `${this.host.dir || documentDirection}`.toLowerCase();
+  }
+
+  /**
+   * Gets the host element's language as determined by the `lang` attribute. The return value is transformed to
+   * lowercase.
+   */
+  lang() {
+    return `${this.host.lang || documentLanguage}`.toLowerCase();
+  }
+
   term<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>) {
+    /** Outputs a localized term. */
     return term(this.host.lang || documentLanguage, key, ...args);
   }
 
+  /** Outputs a localized date in the specified format. */
   date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions) {
     return date(this.host.lang || documentLanguage, dateToFormat, options);
   }
 
+  /** Outputs a localized number in the specified format. */
   number(numberToFormat: number | string, options?: Intl.NumberFormatOptions) {
     return number(this.host.lang || documentLanguage, numberToFormat, options);
   }
 
+  /** Outputs a localized time in relative format. */
   relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) {
     return relativeTime(this.host.lang || documentLanguage, value, unit, options);
   }