feat!: export Locale as named exports (#219)

- allow to import a single Locale via named imports

.gitignore

@@ -27,4 +27,7 @@ dist-ssr
 # Playwright
 playwright-report
 test-results
-/playwright/.cache
+/playwright/.cache
+
+# misc
+tsconfig.tsbuildinfo

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "editor.defaultFormatter": "biomejs.biome",
   "editor.formatOnSave": true,
-  "editor.formatOnPaste": false
+  "editor.formatOnPaste": false,
+  "typescript.tsdk": "node_modules\\typescript\\lib"
 }

README.md

@@ -94,10 +94,6 @@ dist/
   browser/
     multiple-select.js              # ESM build, use with: window.multipleSelect
     multiple-select.cjs             # CJS (CommonJS) build, use with: window.multipleSelect
-  cjs/
-    multiple-select.cjs             # CJS (CommonJS), use with: require()
-  esm/
-    multiple-select.js              # ESM, use with: import from
   locales/
     multiple-select-all-locales.cjs # all-in-1 locales as CJS
     multiple-select-all-locales.js  # all-in-1 locales as ESM
@@ -108,7 +104,9 @@ dist/
   styles/                           # CSS and SASS Stylings
     css/
     sass/
-  types/                            # d.ts Type Definitions
+  index.d.ts                        # d.ts Type Definitions
+  multiple-select.cjs               # CJS (CommonJS), use with: require()
+  multiple-select.js                # ESM, use with: import from
 ```
 
 ### Used by

packages/demo/src/examples/example09.html

@@ -23,9 +23,9 @@ <h2 class="bd-title">
 
 <div>
   <div class="mb-3 row">
-    <label class="col-sm-2"> Locale Select </label>
+    <label class="col-sm-3"> Locale Select </label>
 
-    <div class="col-sm-10">
+    <div class="col-sm-9">
       <select id="locale" class="full-width">
         <option value="en-US">English</option>
         <option value="fr-FR">French</option>
@@ -39,10 +39,10 @@ <h2 class="bd-title">
   </div>
 
   <div class="mb-3 row">
-    <label class="col-sm-2"> Result Select </label>
+    <label class="col-sm-3"> Result Select </label>
 
-    <div class="col-sm-10">
-      <select id="select" class="full-width" multiple="multiple">
+    <div class="col-sm-9">
+      <select id="dynamic-select" class="full-width" multiple="multiple">
         <option value="1">January</option>
         <option value="2">February</option>
         <option value="3">March</option>
@@ -58,4 +58,19 @@ <h2 class="bd-title">
       </select>
     </div>
   </div>
+
+  <hr />
+
+  <div class="mb-3 row">
+    <label class="col-sm-3">named Locale import (Spanish)</label>
+
+    <div class="col-sm-9">
+      <select id="fixed-import" class="full-width" multiple="multiple">
+        <option value="1">First</option>
+        <option value="2">Second</option>
+        <option value="3">Third</option>
+        <option value="4">Fourth</option>
+      </select>
+    </div>
+  </div>
 </div>

packages/demo/src/examples/example09.ts

@@ -1,39 +1,52 @@
-import { MultipleSelectInstance, multipleSelect } from 'multiple-select-vanilla';
+import { type LocaleKey, type MultipleSelectInstance, multipleSelect } from 'multiple-select-vanilla';
 
-// 1. load every locale individually
-// import 'multiple-select-vanilla/dist/locales/multiple-select-fr-FR';
-// import 'multiple-select-vanilla/dist/locales/multiple-select-es-ES';
+// 1. load every locale individually, it could be import in 2 ways (named import OR import on window object)
+import { Spanish } from 'multiple-select-vanilla/dist/locales/multiple-select-es-ES'; // named import
+// import 'multiple-select-vanilla/dist/locales/multiple-select-es-ES';               // locale on window object
 
 // 2. or load all locales at once
 import 'multiple-select-vanilla/dist/locales/multiple-select-all-locales';
 
 export default class Example {
+  ms0?: MultipleSelectInstance;
   ms1?: MultipleSelectInstance;
   ms2?: MultipleSelectInstance;
 
   mount() {
     const elm = document.querySelector('#locale') as HTMLSelectElement;
     elm.addEventListener('change', ((event: KeyboardEvent & { target: HTMLSelectElement }) => {
-      this.updateLocale(event.target.value);
+      this.updateLocale(event.target.value as LocaleKey);
     }) as EventListener);
 
-    this.ms1 = multipleSelect(elm) as MultipleSelectInstance;
-    this.ms2 = multipleSelect('#select', {
+    this.ms0 = multipleSelect(elm) as MultipleSelectInstance;
+    this.ms1 = multipleSelect('#dynamic-select', {
       filter: true,
       showOkButton: true,
+      dataTest: 'select1',
+    }) as MultipleSelectInstance;
+
+    this.ms2 = multipleSelect('#fixed-import', {
+      filter: true,
+      showOkButton: true,
+      dataTest: 'select2',
+
+      // when using named import
+      locale: Spanish,
     }) as MultipleSelectInstance;
   }
 
   unmount() {
     // destroy ms instance(s) to avoid DOM leaks
+    this.ms0?.destroy();
     this.ms1?.destroy();
     this.ms2?.destroy();
+    this.ms0 = undefined;
     this.ms1 = undefined;
     this.ms2 = undefined;
   }
 
-  updateLocale(locale: string) {
-    this.ms2?.destroy();
-    this.ms2?.refreshOptions({ locale });
+  updateLocale(locale: LocaleKey) {
+    this.ms1?.destroy();
+    this.ms1?.refreshOptions({ locale });
   }
 }

packages/demo/src/i18n/i18n.ts

@@ -1,4 +1,4 @@
-import { MultipleSelectInstance, multipleSelect } from 'multiple-select-vanilla';
+import { type MultipleSelectInstance, multipleSelect } from 'multiple-select-vanilla';
 
 export default class Example {
   ms1?: MultipleSelectInstance;
@@ -26,11 +26,13 @@ export default class Example {
       },
 
       // 2. OR you could also use string pattern instead of the callback functions
-      // allSelectedText: 'Tous sélectionnés',
-      // countSelectedText: '# de % selectionnés',
-      // noMatchesFoundText: 'Aucun résultat',
-      // okButtonText: 'Fermer',
-      // selectAllText: 'Tout sélectionner',
+      /*
+      allSelectedText: 'Tous sélectionnés',
+      countSelectedText: '# de % selectionnés',
+      noMatchesFoundText: 'Aucun résultat',
+      okButtonText: 'Fermer',
+      selectAllText: 'Tout sélectionner',
+      */
     }) as MultipleSelectInstance;
   }
 

packages/multiple-select-vanilla/index.d.ts

@@ -8,14 +8,7 @@ declare global {
         config?: Partial<Omit<MultipleSelectOption, 'onHardDestroy' | 'onAfterHardDestroy'>>,
       ): MultipleSelectInstance | MultipleSelectInstance[];
       defaults: Partial<MultipleSelectInstance>;
-      locales: {
-        [localeKey: string]: {
-          formatSelectAll: () => string;
-          formatAllSelected: () => string;
-          formatCountSelected: (count: number, total: number) => string;
-          formatNoMatchesFound: () => string;
-        };
-      };
+      locales: Record<string, MultipleSelectLocale>;
       methods: string[];
     };
   }

packages/multiple-select-vanilla/src/MultipleSelectInstance.ts

@@ -59,7 +59,7 @@ export class MultipleSelectInstance {
   protected _currentHighlightIndex = -1;
   protected _currentSelectedElm?: HTMLLIElement | HTMLDivElement;
   protected isMoveUpRecalcRequired = false;
-  locales: MultipleSelectLocales = {};
+  locales = {} as MultipleSelectLocales;
 
   get isRenderAsHtml() {
     return this.options.renderOptionLabelAsHtml || this.options.useSelectOptionLabelToHtml;
@@ -120,6 +120,11 @@ export class MultipleSelectInstance {
 
   protected initLocale() {
     if (this.options.locale) {
+      if (typeof this.options.locale === 'object') {
+        Object.assign(this.options, this.options.locale);
+        return;
+      }
+
       const locales = window.multipleSelect.locales;
       const parts = this.options.locale.split(/-|_/);
 

packages/multiple-select-vanilla/src/interfaces/index.ts

@@ -1,2 +1,3 @@
 export * from './interfaces';
+export * from './locale.interface';
 export * from './multipleSelectOption.interface';

packages/multiple-select-vanilla/src/interfaces/interfaces.ts

@@ -51,27 +51,6 @@ export interface VirtualScrollOption {
   sanitizer?: (html: string) => string | TrustedHTML;
 }
 
-export interface MultipleSelectLocale {
-  /** Customize the formatted text "All Selected" when using custom locale. */
-  formatAllSelected(): string;
-
-  /** Customize the formatted text "x of y selected" when using custom locale. */
-  formatCountSelected(selectedCount: number, totalCount: number): string;
-
-  /** For the "No Matches Found" text when nothing is found while filtering the dropdown */
-  formatNoMatchesFound(): string;
-
-  /** Customize the formatted text "OK" showing at the bottom of the drop. */
-  formatOkButton(): string;
-
-  /** For the "Select All" checkbox text */
-  formatSelectAll(): string;
-}
-
-export interface MultipleSelectLocales {
-  [localeKey: string]: MultipleSelectLocale;
-}
-
 export interface LabelFilter {
   label: string;
   search: string;

packages/multiple-select-vanilla/src/interfaces/locale.interface.ts

@@ -0,0 +1,34 @@
+/** Locale I18N key (string) that currently exists in the project */
+export type LocaleKey =
+  | 'cz-CS'
+  | 'da-DK'
+  | 'en-US'
+  | 'es-ES'
+  | 'fr-FR'
+  | 'hu-HU'
+  | 'it-IT'
+  | 'ja-JP'
+  | 'pt-BR'
+  | 'ru-RU'
+  | 'vi-VN'
+  | 'zh-CN'
+  | 'zh-TW';
+
+export interface MultipleSelectLocale {
+  /** Customize the formatted text "All Selected" when using custom locale. */
+  formatAllSelected(): string;
+
+  /** Customize the formatted text "x of y selected" when using custom locale. */
+  formatCountSelected(selectedCount: number, totalCount: number): string;
+
+  /** For the "No Matches Found" text when nothing is found while filtering the dropdown */
+  formatNoMatchesFound(): string;
+
+  /** Customize the formatted text "OK" showing at the bottom of the drop. */
+  formatOkButton(): string;
+
+  /** For the "Select All" checkbox text */
+  formatSelectAll(): string;
+}
+
+export type MultipleSelectLocales = Record<LocaleKey, MultipleSelectLocale>;

packages/multiple-select-vanilla/src/interfaces/multipleSelectOption.interface.ts

@@ -1,4 +1,5 @@
-import { LabelFilter, MultipleSelectLocale, OptGroupRowData, OptionRowData, OptionRowDivider, TextFilter } from './interfaces';
+import type { LabelFilter, OptGroupRowData, OptionRowData, OptionRowDivider, TextFilter } from './interfaces';
+import type { LocaleKey, MultipleSelectLocale } from './locale.interface';
 
 export interface MultipleSelectView {
   label: string;
@@ -97,7 +98,7 @@ export interface MultipleSelectOption extends MultipleSelectLocale {
   keepOpen?: boolean;
 
   /** Optional Locale */
-  locale?: string;
+  locale?: LocaleKey | MultipleSelectLocale;
 
   /** Defaults to 250, define the maximum height property of the dropdown list. */
   maxHeight: number;

packages/multiple-select-vanilla/src/locales/multiple-select-cz-CS.ts

@@ -3,11 +3,15 @@
  * Author: Matej Puhony<[email protected]>
  */
 
+import { MultipleSelectInstance } from '../MultipleSelectInstance';
 import { MultipleSelectLocale, MultipleSelectLocales } from '../interfaces';
 
-const ms = window.multipleSelect;
+const ms =
+  typeof window !== 'undefined' && window.multipleSelect !== undefined
+    ? window.multipleSelect
+    : ({ locales: {} as MultipleSelectLocales } as Partial<MultipleSelectInstance>);
 
-(ms.locales as MultipleSelectLocales)['cz-CS'] = {
+export const Czech = {
   formatSelectAll() {
     return '[Vybrat vše]';
   },
@@ -25,4 +29,6 @@ const ms = window.multipleSelect;
   },
 } as MultipleSelectLocale;
 
+(ms.locales as MultipleSelectLocales)['cz-CS'] = Czech;
+
 export default ms.locales;

packages/multiple-select-vanilla/src/locales/multiple-select-da-DK.ts

@@ -3,11 +3,15 @@
  * Author: HThuren<[email protected]>
  */
 
+import { MultipleSelectInstance } from '../MultipleSelectInstance';
 import { MultipleSelectLocale, MultipleSelectLocales } from '../interfaces';
 
-const ms = window.multipleSelect;
+const ms =
+  typeof window !== 'undefined' && window.multipleSelect !== undefined
+    ? window.multipleSelect
+    : ({ locales: {} as MultipleSelectLocales } as Partial<MultipleSelectInstance>);
 
-(ms.locales as MultipleSelectLocales)['da-DK'] = {
+export const Danish = {
   formatSelectAll() {
     return '[Vælg alle]';
   },
@@ -25,4 +29,6 @@ const ms = window.multipleSelect;
   },
 } as MultipleSelectLocale;
 
+(ms.locales as MultipleSelectLocales)['da-DK'] = Danish;
+
 export default ms.locales;

packages/multiple-select-vanilla/src/locales/multiple-select-en-US.ts

@@ -11,24 +11,24 @@ const ms =
     ? window.multipleSelect
     : ({ locales: {} as MultipleSelectLocales } as Partial<MultipleSelectInstance>);
 
-(ms.locales as MultipleSelectLocales) = {
-  'en-US': {
-    formatSelectAll() {
-      return '[Select all]';
-    },
-    formatAllSelected() {
-      return 'All selected';
-    },
-    formatCountSelected(count: number, total: number) {
-      return `${count} of ${total} selected`;
-    },
-    formatNoMatchesFound() {
-      return 'No matches found';
-    },
-    formatOkButton() {
-      return 'OK';
-    },
-  } as MultipleSelectLocale,
-};
+export const English = {
+  formatSelectAll() {
+    return '[Select all]';
+  },
+  formatAllSelected() {
+    return 'All selected';
+  },
+  formatCountSelected(count: number, total: number) {
+    return `${count} of ${total} selected`;
+  },
+  formatNoMatchesFound() {
+    return 'No matches found';
+  },
+  formatOkButton() {
+    return 'OK';
+  },
+} as MultipleSelectLocale;
+
+(ms.locales as MultipleSelectLocales)['en-US'] = English;
 
 export default ms.locales;