docs(site): draft of migration guide for 5.0.0 version

site/views/blogs/ESL v5.0.0 Migartion Guide.md

@@ -0,0 +1,72 @@
+---
+layout: content
+name: ESL v5.0.0 Migartion Guide
+title: Migrating from ESL v4.*.* to ESL v5.0.0
+tags: [news, blogs, draft]
+date: 2024-11-31
+---
+
+The ESL version 5.0.0 have just been released and it comes with a lot of new features and improvements. 
+This guide will help you to migrate your existing ESL v4.\*.* project to ESL v5.0.0.
+
+---
+
+## Preparation
+We recommend you to consider using ESL ESLint plugin to check your codebase for ESL v5.0.0 compatibility.
+It will help you to find and fix most of the issues before you start the migration process.
+The points not marked with `🔧` in the breaking changes section are covered by the ESLint plugin checks and could be fixed automatically.
+
+---
+
+## Breaking Changes
+
+- ### Browser Support
+  ESL v5.0.0 no longer supports IE11 and ES5 target. 
+  ESL UI site renderer and ESL polyfills no longer support Edge old versions and ES6 polyfils.
+  In case by some reason you still need to support IE11 or ES5 target you should use proper transpilation and polyfilling tools on your side.
+
+- ### ESL Core / ESL Utils
+  - #### Direct imports changes
+    - 🔧 `prop`, `attr`, `boolAttr`, `jsonAttr`, `listen` no longer available in `esl-base-element` and `esl-mixin-element` exports,
+    to use them you should import them from `esl-utils/decorators` directly or from the library root.
+  - #### ESL Utils API Changes
+    - `Rect` utility object is now immutable, so you can't change its properties directly. 
+    If you modify the `Rect` object troug builtin methods, you will get a new object with the updated properties.
+  - #### ESL Utils Retired Functianality
+    - `DeviceDetector.TOUCH_EVENTS` and `TOUCH_EVENTS` are retired from the `device-detector` module.
+    - Note that the `DeviceDetector` class is now deprecated. Use direct checks instead.
+    - `createZIndexIframe` and `is-fixes` module are no longer available due to drop of IE11 support.
+    - `RTLUtils` and `TraversingUtils` are retired. Use separate methods instead.
+    - 🔧 `TraversingQuery` is retired as alias. Use `ESLTraversingQuery` instead.
+    - 🔧 `deepCompare` is retired as alias. Use `isEqual` instead.
+    - 🔧 `generateUId` is retired as alias. Use `randUID` instead.
+    - 🔧 `EventUtils` is retired as alias. Use `ESLEventUtils` instead.
+  - #### `SynteticEventTarget` API Changes
+    - `addListener` and `removeListener` shorthand are no longer supported. Use `addEventListener` and `removeEventListener` instead.
+    - `dispatchEvent` no longer accepts the target argument. 
+      You can override the target using `overrideEvent` method from `esl-utils/dom/events`.
+    - 🔧 `ESLEventUtils.descriptors` alias of `ESLEventUtils.getAutoDescriptors` is no longer supported, use full method name instead.
+  - #### ESL Media Query
+    - ESL Media Query consume functionality of `SynteticEventTarget` so `addListener` and `removeListener` shorthand are no longer supported. 
+    Use `addEventListener` and `removeEventListener` instead.
+
+- ### ESL Togglables and Triggers
+  - #### ESL Togglables API Changes
+    - `ToggleableActionParams` alias of `ESLToggleableActionParams` is no longer supported.
+    - `onBeforeShow` and `onBeforeHide` have retired. The constraint now inside `shouldShow`/`shouldHide` methods. 
+      Note that `activator` property change now is the part of main togglable flow.
+    - `this.open` of Toggleables does not updating util super.onShow/super.onHide called. 
+      Make sure you update `this.open` synchronously or manually notify consumers in case the super call of `onShow/onHide` should be postponed.
+  - #### ESL Triggers API Changes
+    - `ESLTrigger` does not have target defined to `::next` by default. You should always define the target explicitly.
+  - #### ESL Panel and Panel Group
+    - `fallback-duration` is no longer in the JSX shape of `ESLPanel` and `ESLPanelGroup`.
+
+- ### ESL Image
+  - CSS aspect-ratio styles are no longer distributed with ESL Image. 
+    You should define them in your project styles or use a separate package for that.
+  - Note that ESL Image is now deprecated. Consider using native Image element with optional help from `esl-image-utils` module. 
+
+- ### ESL Media
+  - `load-cls-target`, `load-cls-accepted` and `load-cls-declined` use `load-condition-class` and `load-condition-class-target` instead.
+  - `disabled` marker no longer supported use `lazy="manual"` instead (the `force` option of `play` method works the same way with new lazy option).