Merge pull request #514 from rdkcentral/release/2.12.0

Release - v2.12.0

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v2.12.0
+*26 oct 2023*
+
+- Introduced a named export for Lightning in the ESM build to support direct module augmentation with `@lightningjs/core`, resolving issues with default export augmentation. (#480)
+- Modified the export structure to support tree-shaking. Lightning's ES modules can now be selectively imported /tree-shaken. (#490)
+- Enabled development in both TypeScript and JavaScript. Migrated specific files and ensured all source module files are appropriately managed in the `dist` directory.
+- Separated the Lightning Inspector with types as its own export.
+- Resolved an inconsistency in the zSorting algorithm where elements with the same zIndex were not correctly sorted by updateTreeOrder. (#443)
+- Addressed an exception causing infinite loops when accessing the texture.source property after text updates. This fix streamlines access to the renderInfo property without triggering a maximum call stack exception. (#447 and #348)
+- Resolved an issue where adding an already existing element to childList would throw an error. (#311 and #509)
+- Fixed an issue where SVG `txError` events were not being triggered due to missed error captures.
+- Fixed an issue where `txLoaded` event in elements over-fired due to incorrect texture change identification.
+
+
 ## v2.11.0
 *31 july 2023*
 

banner.vite-plugin.ts

@@ -12,7 +12,7 @@ export function banner(bannerText: string): Plugin {
     generateBundle(options, bundle) {
       // Add banner to the beginning of each chunk
       Object.keys(bundle).forEach((key) => {
-        const file = bundle[key];
+        const file = bundle[key]!;
         if (file.type === 'chunk') {
           file.code = bannerText + '\n' + file.code;
         }

src/inspector.d.mts → devtools/lightning-inspect.d.ts

@@ -2,7 +2,7 @@
  * If not stated otherwise in this file or this component's LICENSE file the
  * following copyright and licenses apply:
  *
- * Copyright 2022 Metrological
+ * Copyright 2023 Metrological
  *
  * Licensed under the Apache License, Version 2.0 (the License);
  * you may not use this file except in compliance with the License.
@@ -16,10 +16,28 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import lng from './lightning.mjs';
+import type {
+  Application,
+  Component,
+  Element,
+  ElementCore,
+  ElementTexturizer,
+  Stage,
+  Texture,
+} from "../dist/src";
+
+declare interface ILng {
+  Application?: typeof Application;
+  Component?: typeof Component;
+  Element: typeof Element;
+  ElementCore: typeof ElementCore;
+  ElementTexturizer: typeof ElementTexturizer;
+  Stage: typeof Stage;
+  Texture: typeof Texture;
+}
 
 declare global {
   interface Window {
-    attachInspector?(Lightning: typeof lng): void;
+    attachInspector(lng: ILng): void;
   }
 }

devtools/lightning-inspect.js

@@ -843,18 +843,20 @@ window.attachInspector = function({Application, Element, ElementCore, Stage, Com
         updateTextureAttribs(this)
     }
 
-    const _updateFocus = Application.prototype.__updateFocus
-    Application.prototype.__updateFocus = function() {
-        const prev = this._focusPath && this._focusPath.length ? this._focusPath[this._focusPath.length - 1] : null;
-        _updateFocus.apply(this, arguments)
-        const focused = this._focusPath && this._focusPath.length ? this._focusPath[this._focusPath.length - 1] : null;
-
-        if (prev != focused) {
-            if (prev) {
-                val(prev, 'focused', false, false);
-            }
-            if (focused) {
-                val(focused, 'focused', true, false);
+    if (typeof Application !== "undefined") {
+        const _updateFocus = Application.prototype.__updateFocus
+        Application.prototype.__updateFocus = function() {
+            const prev = this._focusPath && this._focusPath.length ? this._focusPath[this._focusPath.length - 1] : null;
+            _updateFocus.apply(this, arguments)
+            const focused = this._focusPath && this._focusPath.length ? this._focusPath[this._focusPath.length - 1] : null;
+
+            if (prev != focused) {
+                if (prev) {
+                    val(prev, 'focused', false, false);
+                }
+                if (focused) {
+                    val(focused, 'focused', true, false);
+                }
             }
         }
     }

docs/PackageExports/index.md

@@ -0,0 +1,49 @@
+# Package Exports / Tree Shaking
+
+The Lightning Core NPM package exports both the Lightning Core library (the default package export: "@lightningjs/core") as well as the Lightning Inspector ("@lightningjs/core/inspector"). Both the [ES](https://nodejs.org/api/esm.html#modules-ecmascript-modules) and [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) module styles are supported by both package exports.
+
+> CommonJS is currently provided mainly to support older build tooling that may still be in use by applications. It is recommended that you upgrade/configure your build tools/bundler to utilize the ES modules when possible.
+
+## Lightning Core (Tree Shakable ESM Exports)
+
+```js
+// ESM (tree shakable named exports)
+import { Application, Component } from "@lightningjs/core";
+```
+
+Lightning Core has historically always been available as a single default exported object from which you can access all of the various Lightning classes. As of version 2.12, when using ESM, each Lightning class is now also available as a seperate tree shakable named export.
+
+Exclusively using the named ESM exports in your application enables the potential for your chosen bundler to [tree shake](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) Lightning's code so that the parts of Lightning that are not utilized by your application are left out of your bundle, reducing its size.
+
+> Important: In order for tree shaking to be successful, your entire application, including any dependencies that are also dependent on Lightning must also utilize the named ESM exports. At the time of this writing, no published Lightning-based NPM packages utilize the tree shakable exports. So if your application is dependent on any, your bundler will be unable to tree shake Lightning.
+
+## Lightning Core (Default Export)
+
+```js
+// ESM (default export)
+import Lightning from "@lightningjs/core";
+
+// CommonJS
+const Lightning = require("@lightningjs/core");
+```
+
+The default export, as mentioned above, has historically been the main way users import Lightning Core. All of Lightning Core is available from this single exported object and as such, if imported, will prevent your chosen bundler from being able to tree shake Lightning.
+
+## Lightning Inspector
+
+```js
+// ESM
+import "@lightningjs/core/inspector";
+
+// ESM (Dynamic)
+await import("@lightningjs/core/inspector");
+
+// CommonJS
+require("@lightningjs/core/inspector");
+```
+
+Outside of including the Lightning Inspector via a seperate `<script>` tag in your application's HTML, you can import/require it as of version 2.12:
+
+The Inspector itself does not export any functions/classes/etc via either module style, but it does execute when included and places an `attachInspector()` method onto the browser's `window` object.
+
+> If you choose this method, care should be taken to make sure the Inspector is not bundled with production code.

docs/TypeScript/Augmentation.md

@@ -4,6 +4,8 @@ There are certain global type structures provided by Lightning Core that your ap
 
 The following are the TypeScript interfaces exported by Lightning Core that are designed for augmentation. You may find need to augment other available interfaces. In this event, please let us know what interfaces you are augmenting so we may add use guidelines to this page (or submit a [PR](https://github.com/rdkcentral/Lightning/pulls)!).
 
+> As of version 2.12, interface augmentation can be done without using the Lightning SDK or other hacks.
+
 ## Component Key Handlers
 
 Key Handlers are the methods you implement in your Components in order to handle key events. These are based on the Key Map provided during Application initialization. Often times the default set of key handlers that come with Lightning are good enough. But sometimes you need to add additional keys to it or replace it altogether. Lightning's TypeScript implementation includes the default key map set of handlers in the Component class. This allows you to write your class and have TypeScript make sure the parameters/return values are proper:
@@ -39,17 +41,13 @@ See the examples below.
 When this interface is augmented, you add additional key handlers to the existing default set.
 
 ```ts
-import '@lightningjs/sdk'
-
-declare module '@lightningjs/sdk' {
-  namespace Lightning {
-    namespace Component {
-      interface DefaultKeyHandlers {
-        _captureHome?(e: KeyboardEvent): boolean | void;
-        _captureHomeRelease?(e: KeyboardEvent): boolean | void;
-        _handleHome?(e: KeyboardEvent): boolean | void;
-        _handleHomeRelease?(e: KeyboardEvent): boolean | void;
-      }
+declare module '@lightningjs/core' {
+  namespace Component {
+    interface DefaultKeyHandlers {
+      _captureHome?(e: KeyboardEvent): boolean | void;
+      _captureHomeRelease?(e: KeyboardEvent): boolean | void;
+      _handleHome?(e: KeyboardEvent): boolean | void;
+      _handleHomeRelease?(e: KeyboardEvent): boolean | void;
     }
   }
 }
@@ -62,37 +60,29 @@ When this interface is augmented, the entire set of `DefaultKeyHandlers` are rep
 
 Example:
 ```ts
-import '@lightningjs/sdk'
-
-declare module '@lightningjs/sdk' {
-  namespace Lightning {
-    namespace Component {
-      interface CustomKeyHandlers {
-        _captureHome?(e: KeyboardEvent): boolean | void;
-        _captureHomeRelease?(e: KeyboardEvent): boolean | void;
-        _handleHome?(e: KeyboardEvent): boolean | void;
-        _handleHomeRelease?(e: KeyboardEvent): boolean | void;
-      }
+declare module '@lightningjs/core' {
+  namespace Component {
+    interface CustomKeyHandlers {
+      _captureHome?(e: KeyboardEvent): boolean | void;
+      _captureHomeRelease?(e: KeyboardEvent): boolean | void;
+      _handleHome?(e: KeyboardEvent): boolean | void;
+      _handleHomeRelease?(e: KeyboardEvent): boolean | void;
     }
   }
 }
 ```
 
 ## Lightning.Component.FireAncestorsMap
 
-Augmenting this interface this allows you to globally add to the events available in the `firstAncestors()` method available in any Component.
+Augmenting this interface this allows you to globally add to the events available in the `fireAncestors()` method available in any Component.
 
 Example:
 ```ts
-import '@lightningjs/sdk'
-
-declare module '@lightningjs/sdk' {
-  namespace Lightning {
-    namespace Component {
-      interface FireAncestorsMap {
-        $itemCreated(): void;
-        $selectItem(item: string, index: number): void;
-      }
+declare module '@lightningjs/core' {
+  namespace Component {
+    interface FireAncestorsMap {
+      $itemCreated(): void;
+      $selectItem(item: string, index: number): void;
     }
   }
 }
@@ -111,16 +101,12 @@ Some applications opt to use the root Application component (available from any
 
 Example:
 ```ts
-import '@lightningjs/sdk'
-
-declare module '@lightningjs/sdk' {
-  namespace Lightning {
-    namespace Application {
-      interface EventMap {
-        titleLoaded(): void;
-        ratingColor(color: number): void;
-        setBackground(evt: { src: string }): void;
-      }
+declare module '@lightningjs/core' {
+  namespace Application {
+    interface EventMap {
+      titleLoaded(): void;
+      ratingColor(color: number): void;
+      setBackground(evt: { src: string }): void;
     }
   }
 }

docs/index.md

@@ -5,6 +5,7 @@ The Reference Documentation for Lightning Core contains detailed descriptions ab
 
 ## Table of Contents
 <!---TOC_start--->
+* [Package Exports / Tree Shaking](PackageExports/index.md)
 * [Runtime Configuration](RuntimeConfig/index.md)
 * [Render Engine](RenderEngine/index.md)
   * [Render Tree](RenderEngine/RenderTree.md)

fixTsImportsFromJs.vite-plugin.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from 'vite';
+
+/**
+ * This Vite plugin ensures that TypeScript modules imported from JavaScript
+ * modules are resolved correctly.
+ */
+export function fixTsImportsFromJs(): Plugin {
+  return {
+    name: 'fix-ts-imports-from-js',
+    async resolveId(source, importer = '', options) {
+      let resolution = await this.resolve(source, importer, {
+        skipSelf: true,
+        ...options
+      });
+      // If there was no resolution and the importer file is JavaScript and the source
+      // ends in `.js` lets see if we can resolve a `.ts` file
+      if (!resolution && (importer.endsWith('.js') || importer.endsWith('.mjs')) &&
+        (source.endsWith('.js') || source.endsWith('.mjs'))) {
+        const newSource = source.replace(/\.mjs$/, '.mts').replace(/\.js$/, '.ts');
+        resolution = await this.resolve(newSource, importer, {
+          skipSelf: true,
+          ...options
+        });
+      }
+      return resolution;
+    },
+  };
+}