feat!: drop standalone legacy browser <script> & window object usage (#461)

* feat!: drop standalone legacy browser <script> & use of  `window` object

Author: ghiscoding

README.md

@@ -140,29 +140,59 @@ with this code in place, we can now use the following CSP meta tag (which is wha
 > [!NOTE]
 > in our demo we are only adding `unsafe-inline` simply because we are using Vite (which is not CSP compliant in Dev mode), but the library should work nonetheless without `unsafe-inline`.
 
+## Major Changes
+
+### version 3.0
+- remove deprecated options
+- new Modern Look by using SVG icons
+
+### version 4.0
+- build ESM-Only and drop CJS (CommonJS) build (aka `require()`)
+
+### version 5.0
+
+Locale management has been refactored to remove usage of the global `window` object. Locales are now provided via a modular registry and injected through options. This change affects how you load, switch, and reference locales. Also, the `multiple-select-` prefix has been removed from all locale import paths (single and merged) and no longer exists on the `window` object
+
+**Migration Example:**
+
+```diff
+// 1. load every locale individually, it could be import in 2 ways (named import OR import on window object)
+- // named import
+- import { Spanish } from 'multiple-select-vanilla/dist/locales/multiple-select-es-ES.js';
+- // OR default import
+- import 'multiple-select-vanilla/dist/locales/multiple-select-es-ES.js';
++ // named import
++ import { Spanish } from 'multiple-select-vanilla/dist/locales/es-ES.js';
++ // OR default import
++ import Spanish from 'multiple-select-vanilla/dist/locales/es-ES.js';
+
+// 2. or load all locales at once
+- import 'multiple-select-vanilla/dist/locales/multiple-select-all-locales';
++ // named import
++ import { locales } from 'multiple-select-vanilla/dist/locales/all-locales.js';
++ // OR default import
++ import locales from 'multiple-select-vanilla/dist/locales/all-locales.js';
+```
+
+See the [Example09](https://ghiscoding.github.io/multiple-select-vanilla/#/example09) for details on dynamic locale loading.
+
 ### Installation / Structure
 
-There are multiple ways to install and use the library, you can see below the folder structure of the distribution files
-1. `dist/browser`: Standalone build which assigns `multipleSelect` on the `window.multipleSelect` object
-   - browser standalone means that you can simply load it with `<script></script>` and then `multipleSelect('#mySelect')`
-   - only ESM build (`.js`) are provided, you will need to load it with `<script type="module">`
-2. `esm`: to use as ESM with `import from 'multiple-select-vanilla'`
+The library is now ESM Only, the library does include optional locales that can be loaded through imports or you can use and define your own custom texts as well. Here's the full library structure of the project
 
 ```
 dist/
-  browser/
-    multiple-select.js              # ESM build, use with: window.multipleSelect
   locales/
-    multiple-select-all-locales.js  # all-in-1 locales
+    all-locales.js    # all-in-1 locales
     ..
-    multiple-select-es-ES.js        # Spanish locale
-    multiple-select-fr-FR.js        # French locale
+    es-ES.js          # Spanish locale
+    fr-FR.js          # French locale
     ...
-  styles/                           # CSS and SASS Stylings
+  styles/             # CSS and SASS Stylings
     css/
     sass/
-  index.d.ts                        # d.ts Type Definitions
-  multiple-select.js                # ESM, used by: import from
+  index.d.ts          # d.ts Type Definitions
+  index.js            # ESM import
 ```
 
 ### Used by
@@ -228,8 +258,4 @@ Before submitting a PR (pull request), please make sure that you followed the st
   <span>
     <a href="https://github.com/gibson552" class="Link" title="gibson552" target="_blank"><img src="https://avatars.githubusercontent.com/u/84058359?s=52&v=4" width="50" height="50" valign="middle" /></a>
   </span>
-  &nbsp;
-  <span>
-    <a href="https://github.com/web-ascender" class="Link" title="Web Ascender" target="_blank"><img src="https://avatars.githubusercontent.com/u/832747?s=200&v=4" width="50" height="50" valign="middle" /></a>
-  </span>
 </div>

packages/demo/src/examples/example09.html

@@ -18,16 +18,17 @@ <h2 class="bd-title">
       </span>
     </h2>
     <div class="demo-subtitle">
-      Use <code>locale</code>to set the locale.
+      Use <code>locale</code>to set the locale. <strong>Please note</strong> that the months themselves aren't being translated, but every
+      other labels like "Select All", "OK", "Cancel", "Search", etc. are the ones being translated.
     </div>
   </div>
 </div>
 
 <div>
   <div class="mb-3 row">
-    <label class="col-sm-3">Locale Select </label>
+    <label class="col-sm-4">Locale Select </label>
 
-    <div class="col-sm-9">
+    <div class="col-sm-8">
       <select id="locale" class="full-width">
         <option value="en-US">English</option>
         <option value="fr-FR">French</option>
@@ -43,9 +44,9 @@ <h2 class="bd-title">
   </div>
 
   <div class="mb-3 row">
-    <label class="col-sm-3">Result Select </label>
+    <label class="col-sm-4">Result Select </label>
 
-    <div class="col-sm-9">
+    <div class="col-sm-8">
       <select id="dynamic-select" class="full-width" multiple="multiple">
         <option value="1">January</option>
         <option value="2">February</option>
@@ -62,13 +63,26 @@ <h2 class="bd-title">
       </select>
     </div>
   </div>
+  <div class="row">
+    <div style="background: #f7f7f7; padding: 10px">
+      <pre>
+// ESM named import
+<span style="color:#cf222e">import</span> { locales } <span style="color:#cf222e">from</span> <span style="color:#0a3069">'multiple-select-vanilla/dist/locales/all-locales.js'</span>;
+<span style="color:#6639ba">multipleSelect</span>(<span style="color:#0a3069">'.select'</span>, {
+  locales
+}</span>);
+</pre>
+    </div>
+  </div>
 
   <hr>
 
   <div class="my-5 row">
-    <label class="col-sm-3">named Locale import (i.e. Spanish)</label>
+    <label class="col-sm-4">
+      named Locale import (e.g. <code>Spanish</code>)
+    </label>
 
-    <div class="col-sm-9">
+    <div class="col-sm-8">
       <select id="fixed-import" class="full-width" multiple="multiple">
         <option value="1">First</option>
         <option value="2">Second</option>
@@ -77,4 +91,15 @@ <h2 class="bd-title">
       </select>
     </div>
   </div>
+  <div class="row">
+    <div style="background: #f7f7f7; padding: 10px">
+      <pre>
+// ESM named import
+<span style="color:#cf222e">import</span> { multipleSelect } <span style="color:#cf222e">from</span> <span style="color:#0a3069">'multiple-select-vanilla'</span>;
+<span style="color:#6639ba">multipleSelect</span>(<span style="color:#0a3069">'.select'</span>, {
+  locale: <span style="color:#105fd7">Spanish</span>
+}</span>);
+</pre>
+    </div>
+  </div>
 </div>

packages/demo/src/examples/example09.ts

@@ -1,11 +1,11 @@
 import { type LocaleKey, type MultipleSelectInstance, multipleSelect } from 'multiple-select-vanilla';
 
 // 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
+import { Spanish } from 'multiple-select-vanilla/dist/locales/es-ES.js'; // named import
+// import 'multiple-select-vanilla/dist/locales/es-ES';               // locale on window object
 
 // 2. or load all locales at once
-import 'multiple-select-vanilla/dist/locales/multiple-select-all-locales';
+import { locales } from 'multiple-select-vanilla/dist/locales/all-locales.js';
 
 export default class Example {
   ms0?: MultipleSelectInstance;
@@ -25,6 +25,7 @@ export default class Example {
       filter: true,
       showOkButton: true,
       dataTest: 'select1',
+      locales,
     }) as MultipleSelectInstance;
 
     this.ms2 = multipleSelect('#fixed-import', {

packages/demo/src/getting-started.html

@@ -16,26 +16,18 @@ <h5>GitHub <i class="fa fa-link"></i></h5>
   <section>
     <h5>CDN</h5>
     <p>
-      <a href="https://www.jsdelivr.com/" target="__blank">jsDelivr</a>&nbsp;graciously provide CDNs for many JavaScript libraries including
-      Multiple-Select-Vanilla. Just use the following CDN links.
-    </p>
-    <p>
-      The project now ships as ESM-Only, if you still wish to use the legacy CommonJS (CJS) format with <code>require()</code>, then use
-      previous 3.x version.
+      <a href="https://www.jsdelivr.com/" target="__blank">jsDelivr</a>
+      graciously provide CDNs for many JavaScript libraries including Multiple-Select-Vanilla. Just use the following CDN links.
     </p>
 
     <div style="background: #f7f7f7; padding: 10px">
       <pre>
-&lt;!-- Get latest compiled and minified CSS --&gt;
-&lt;link href=&quot;<span style="color:#0a3069">https://cdn.jsdelivr.net/npm/multiple-select-vanilla@4.3.5/dist/styles/css/multiple-select.css</span>&quot; rel=&quot;<span style="color:#0a3069">stylesheet</span>&quot;&gt;
-
-&lt;!-- ESM import requires <span style="color:#d63384">type=&quot;module&quot;</span>, get latest compiled and minified JavaScript code --&gt;
-&lt;script type=&quot;module&quot; src=&quot;<span style="color:#0a3069">https://cdn.jsdelivr.net/npm/multiple-select-vanilla@4.3.5/dist/browser/multiple-select.js</span>&quot;&gt;&lt;/script&gt;
+&lt;script <span style="color:#207eb1">type</span>=&quot;<span style="color:#d7742d">module</span>&quot;&gt;
+  // ESM Module import
+  <span style="color:#cf222e">import</span> multipleSelect <span style="color:#cf222e">from</span> <span style="color:#0a3069">'https://cdn.jsdelivr.net/npm/multiple-select-vanilla@5.0.0/+esm'</span>;
+&lt;/script&gt;
+</pre>
     </div>
-
-    <quote>
-      <b>Note:</b> the <code>dist/browser</code> location is the only one providing the <code>MultipleSelect</code> on the <code>window</code> object.
-    </quote>
   </section>
 
   <section>
@@ -92,4 +84,9 @@ <h5>CSS / SASS Styling Themes</h5>
 </pre>
     </div>
   </section>
+  <h5>Legacy Versions</h5>
+  <p>
+    The project now ships as ESM-Only, if you still wish to use the legacy <code>&lt;script&gt;</code> standalone IIFE Script on the
+    <code>window</code> object, then use the previous 4.x version.
+  </p>
 </div>

packages/multiple-select-vanilla/README.md

@@ -37,7 +37,7 @@ import { multipleSelect } from 'multiple-select-vanilla';
 
 const ms = multipleSelect('.multiple-select', {
   data: ['First', 'Second'] // native string/number/boolean
-};
+});
 
 const ms = multipleSelect('.multiple-select', {
   data: [
@@ -57,3 +57,39 @@ const ms = multipleSelect('.multiple-select', {
 ## LICENSE
 
 [MIT License](https://github.com/ghiscoding/multiple-select-vanilla/blob/main/LICENSE)
+
+## Major Changes
+
+### version 3.0
+- remove deprecated options
+- new Modern Look by using SVG icons
+
+### version 4.0
+- build ESM-Only and drop CJS (CommonJS) build (aka `require()`)
+
+### version 5.0
+
+Locale management has been refactored to remove usage of the global `window` object. Locales are now provided via a modular registry and injected through options. This change affects how you load, switch, and reference locales. Also, the `multiple-select-` prefix has been removed from all locale import paths (single and merged) and no longer exists on the `window` object
+
+**Migration Example:**
+
+```diff
+// 1. load every locale individually, it could be import in 2 ways (named import OR import on window object)
+- // named import
+- import { Spanish } from 'multiple-select-vanilla/dist/locales/multiple-select-es-ES.js';
+- // OR default import
+- import 'multiple-select-vanilla/dist/locales/multiple-select-es-ES.js';
++ // named import
++ import { Spanish } from 'multiple-select-vanilla/dist/locales/es-ES.js';
++ // OR default import
++ import Spanish from 'multiple-select-vanilla/dist/locales/es-ES.js';
+
+// 2. or load all locales at once
+- import 'multiple-select-vanilla/dist/locales/multiple-select-all-locales';
++ // named import
++ import { locales } from 'multiple-select-vanilla/dist/locales/all-locales.js';
++ // OR default import
++ import locales from 'multiple-select-vanilla/dist/locales/all-locales.js';
+```
+
+See the [Example09](https://ghiscoding.github.io/multiple-select-vanilla/#/example09) for details on dynamic locale loading.

packages/multiple-select-vanilla/build-prod.mjs

@@ -3,41 +3,31 @@ import { globSync } from 'tinyglobby';
 
 const buildFormats = ['esm'];
 const localeFiles = globSync('src/locales/**/*.ts');
-const localeEntryPoints = [];
 
 for (const format of buildFormats) {
   runBuild({
     format,
     outfile: `dist/index.js`,
   });
 
-  // build all locales
+  // build all locales (short names, e.g. "es-ES.ts")
   for (const localeFile of localeFiles) {
-    // eslint-disable-next-line no-unused-vars
-    const [_, locale] = localeFile.match(/multiple-select-(.*)\.ts$/) || [];
-    if (locale && locale.length === 5) {
-      localeEntryPoints.push(`src/locales/multiple-select-${locale}.ts`);
+    const match = localeFile.match(/src\/locales\/(..-..).ts$/);
+    if (match?.[1] && !['index', 'all-locales'].includes(match[1])) {
+      const locale = match[1];
       runBuild({
-        entryPoints: [`src/locales/multiple-select-${locale}.ts`],
+        entryPoints: [localeFile],
         format,
-        outfile: `dist/locales/multiple-select-${locale}.js`,
+        outfile: `dist/locales/${locale}.js`,
       });
     }
   }
 
-  // also merge all Locales into a single file "multiple-select-all-locales.js"
+  // also merge all Locales into a single file "all-locales.js" (the registry)
   runBuild({
-    entryPoints: ['./src/locales/all-locales-index.ts'],
+    entryPoints: ['./src/locales/all-locales.ts'],
     format,
-    outfile: `dist/locales/multiple-select-all-locales.js`,
-  });
-
-  // finally, create a regular bundle as a standalone which will be accessible as MultipleSelect from the global window object
-  // this file is basically a legacy alternative to import via a <script> tag
-  runBuild({
-    format,
-    globalName: 'MultipleSelect',
-    outfile: `dist/browser/multiple-select.js`,
+    outfile: `dist/locales/all-locales.js`,
   });
 }
 

packages/multiple-select-vanilla/build-watch.mjs

@@ -1,8 +1,9 @@
 import { exec, execSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { copyfiles } from 'native-copyfiles';
+
 import { buildSync } from 'esbuild';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { copyfiles } from 'native-copyfiles';
 import { compile as sassCompile } from 'sass';
 
 const env = process.env.NODE_ENV;
@@ -33,11 +34,11 @@ function runBuild(options) {
 }
 
 function runMergedLocaleBuild() {
-  // merge all Locales into a single file "multiple-select-all-locales.js"
+  // merge all Locales into a single file "all-locales.js"
   runBuild({
-    entryPoints: ['./src/locales/all-locales-index.ts'],
+    entryPoints: ['./src/locales/all-locales.ts'],
     format: 'esm',
-    outfile: 'dist/locales/multiple-select-all-locales.js',
+    outfile: 'dist/locales/all-locales.js',
   });
 }
 
@@ -57,12 +58,13 @@ async function runCompilation(changedFiles) {
       }
       if (changedFile.includes('locales')) {
         // rebuild changed locale and also merged locale into a single locale
-        const [_, locale] = changedFile.match(/locales[\\/]multiple-select-(.*)\.ts$/) || [];
-        if (locale?.length === 5) {
+        const match = changedFile.match(/locales[\\/](..-..).ts$/);
+        if (match?.[1] && !['index', 'all-locales'].includes(match[1])) {
+          const locale = match[1];
           runBuild({
-            entryPoints: [`src/locales/multiple-select-${locale}.ts`],
+            entryPoints: [`src/locales/${locale}.ts`],
             format: 'esm',
-            outfile: `dist/locales/multiple-select-${locale}.js`,
+            outfile: `dist/locales/${locale}.js`,
           });
         }
         runMergedLocaleBuild();