Upgrade: add 4.0 upgrade guide

pages/upgrade-guide/4.0.md

@@ -3,6 +3,9 @@
 	"toc": true
 }</script>
 
+> [!NOTE]
+> jQuery 4.0 is not yet released. This is a draft of the jQuery 4.0 upgrade guide. jQuery 4.0 is currently in development and this guide will be updated as changes are finalized. The jQuery team welcomes feedback on this guide and the changes in jQuery 4.0.
+
 ## Overview
 
 With the major version of 4.0, the jQuery Core team has taken the opportunity to make changes to clean up the API and fix bugs that may prove to be breaking changes for some. This includes the removal of previously deprecated public APIs, changes to or removal of undocumented APIs, and changes to the documented or undocumented behavior of existing APIs for specific inputs.
@@ -17,6 +20,15 @@ As of jQuery 4.0, the following browsers are supported:
 * Safari Mobile iOS: Current and Current - 1
 * Android: Current and Current - 1
 
+### Browsers no longer supported
+
+* Edge: Legacy (non-Chromium) versions
+* Internet Explorer: 10 and below
+* Chrome, Edge, Firefox, Safari: All versions older than Current - 1
+* Opera: All versions older than Current
+* Safari Mobile iOS: All versions older than Current - 1
+* Android: All versions older than Current - 1
+
 Browser support will not change until the next major version of jQuery (5.0).
 
 ## jQuery Migrate Plugin
@@ -66,7 +78,7 @@ For a complete and detailed list of all code changes, see the 3.0 milestone in t
 
 #### Breaking change: JSON to JSONP auto-promotion removed
 
-Previously, `jQuery.ajax` with `dataType: 'json'` with a provided callback was automatically converted to a JSONP request unless one also specified `jsonp: false`. Today, the preferred way of interacting with a cross-domain backend is CORS, which works in all browsers jQuery 4 supports.
+Previously, `jQuery.ajax` with `dataType: "json"` with a provided callback was automatically converted to a JSONP request unless one also specified `jsonp: false`. Today, the preferred way of interacting with a cross-domain backend is CORS, which works in all browsers jQuery 4 supports.
 
 Auto-promoting JSON requests to JSONP introduced a security issue. The developer may be unaware they are executing code from a remote domain. The auto-promoting logic has been disabled.
 
@@ -84,9 +96,13 @@ Until jQuery 4.0, the AJAX script transport only used a script tag to load scrip
 
 This change may affect existing code if certain scripts were expected to execute even when CSP headers were set. Either modify the CSP header to allow scripts from the same domain or remove the scripts.
 
+#### Potentially breaking change: `jQuery.ajax` now supports binary data
+
+jQuery 4.0 adds support for binary data in `jQuery.ajax` requests by adding support for `FormData` objects passed to the `data` argument. This change may affect existing code that relies on the previous behavior of `jQuery.ajax` when passing non-serializable data types, especially code that relies on the order of the execution of Ajax prefilters. Before, data was converted to a string before prefilters could be applied. Still, we don't expect this change to affect most users.
+
 ### Attributes
 
-#### Breaking change: `toggleClass(boolean | undefined)` signature removed
+#### Breaking change: `toggleClass( Boolean | undefined )` signature removed
 
 This particular signature was deprecated in jQuery 3.0 and is now being removed in jQuery 4.0. After feedback and discussion with the community, it was determined that this signature caused unexpected behavior. For instance, if the argument to `toggleClass` was a variable that turned out to be `undefined` or `false`, it would result in all classes being removed. Also, while the `toggleClass( boolean )` signature was documented (and has been marked deprecated since 3.0), the `toggleClass( undefined )` signature was not.
 
@@ -105,15 +121,37 @@ The following APIs were deprecated in previous versions and have been removed in
 	This object was used to map CSS properties to their vendor-prefixed versions, which is no longer necessary in jQuery 4.0's supported browsers.
 
 * `jQuery.isArray`
+	Use Array.isArray.
+
 * `jQuery.isFunction`
+	Use typeof value === "function".
+
 * `jQuery.isNumeric`
+	Use Number.isFinite or a custom implementation.
+
 * `jQuery.isWindow`
+	Window detection is generally unreliable and discouraged. If absolutely necessary, use `obj != null && obj === obj.window`.
+
 * `jQuery.fx.interval`
-* `jQuery.parseJSON`
+	The default value was 13 (milliseconds), but has been removed as it does not work well with `requestAnimationFrame`. It should no longer be necessary.
+
 * `jQuery.nodeName`
+	Use `element.nodeName.toLowerCase()`.
+
 * `jQuery.now`
+	Use `Date.now()`.
+
+* `jQuery.parseJSON`
+	Use JSON.parse.
+
 * `jQuery.trim`
+	Use String.prototype.trim.
+
 * `jQuery.type`
+	`typeof` is sufficient for most cases.
+
+* `jQuery.unique`
+  Use `jQuery.uniqueSort`.
 
 #### Breaking change: Remove undocumented Array methods
 
@@ -123,13 +161,17 @@ jQuery 4.0 removes `push`, `sort`, and `splice` from the jQuery prototype. These
 
 The slim build of jQuery 4.0 no longer includes the `callbacks` and `deferred` modules. Use the full build if you need these modules, or use native Promise objects.
 
-#### Breaking change: Remove undocumented `root` parameter of `jQuery()`
+#### Breaking change: Remove undocumented `root` parameter of `jQuery.fn.init()`
 
-The `root` parameter of `jQuery()` was never documented and was only used internally. Also, it has not been necessary since jQuery 1.9 when `jQuery.sub()` was removed.
+`root` was the third parameter of `jQuery.fn.init()`, but was never documented and was only used internally. Also, it has not been necessary since jQuery 1.9 when `jQuery.sub()` was removed.
 
 #### Important fix: Add `exports` to package.json
 
-jQuery exports multiple builds that can be used in different environments. This includes the default build as both a universal module (UMD) and an ESM module, the slim build in UMD and ESM, and a factory build for running jQuery with DOM emulators like JSDOM. The `exports` field in `package.json` is used to specify which build is used in different environments. This change is not expected to affect existing code.
+jQuery exports multiple builds that can be used in different environments. This includes the default build as both a universal module (UMD) and an ESM module, the slim build in UMD and ESM, and a factory build for running jQuery with DOM emulators like JSDOM. The `exports` field in `package.json` is used to specify which build is used in different environments. This change should not affect existing code in most cases, but it is an important fix to ensure that jQuery can be used in a wider range of environments. In fact, jQuery now exports a separate "factory" version for use in Node where the DOM is not available, such as in testing environments like JSDOM. This used to be supported by the main jQuery file, but it is now a separate build and the `exports` field ensures that it is used correctly.
+
+#### Potentially breaking change: jQuery's source is no longer written using AMD modules
+
+jQuery's source code has been converted to use ES modules instead of AMD modules. While this has several advantages, some users may have been importing jQuery's source directly using AMD loaders such as RequireJS. This change may affect those users, but it is expected that most users will be able to continue using jQuery without any issues. The main jQuery file is still built as a UMD module, so it can be used in both AMD and non-AMD environments.
 
 ### CSS
 
@@ -139,27 +181,33 @@ jQuery 4.0 switches strategies when it comes to setting CSS properties that requ
 
 Instead, jQuery will now only add `px` to a limited set of properties that are known to require it. This change may affect existing code that relies on the old behavior.
 
+#### Breaking change: Remove opacity CSS hook
+
+`.css( "opacity" )` will now return an empty string for detached elements in standard-compliant browsers and "1" in IE. That behavior is shared by most other CSS properties, but may affect existing code relying on a return value of "1".
+
 ### Data
 
 #### Important fix: `Object.prototype` pollution
 
-jQuery 4.0 includes a fix to ensure event and data keys matching `Object.prototype` properties are supported without overriding the native properties. This change is not expected to affect existing code unless it specifically used native property names as event or data keys, which may have caused unexpected behavior anyway.
+jQuery 4.0 includes a fix to ensure event and data keys matching `Object.prototype` properties are supported without overriding the native properties. This change is not expected to affect existing code.
 
 ### Deferred
 
-#### Breaking change: Removed jQuery.Deferred.getStackHook
+#### Breaking change: Removed `jQuery.Deferred.getStackHook`
 
-This has been renamed since 3.7.0 to jQuery.Deferred.getErrorHook. It is used to pass the original error to jQuery.Deferred.exceptionHook. Previously, we recommended passing the stack but that didn't play well with source maps.
+This has been renamed since 3.7.0 to `jQuery.Deferred.getErrorHook`. It is used to pass the original error to `jQuery.Deferred.exceptionHook`. Previously, we recommended passing the stack but that didn't play well with source maps. `jQuery.Deferred.exceptionHook` can be used to debug asynchronous errors.
+
+TODO: link to documentation
 
 ### Event
 
 #### Breaking change: Stop shimming focusin & focusout events
 
-jQuery 4.0 no longer shims the `focusin` and `focusout` events. This only affects code that relies on the order of these events as they relate to `focus` and `blur`. This change is expected to affect very few users.
+jQuery 4.0 no longer shims the `focusin` and `focusout` events. This only affects code that relies on the order of these events as they relate to `focus` and `blur`. This change is expected to affect very few users. Mostly, the order can be different in IE in that `blur` can come before `focousout` and `focus` before `focusin`. See [#4362](https://github.com/jquery/jquery/pull/4362) for details.
 
-#### Breaking change: Avoid collisions between jQuery.event.special & Object.prototype
+#### Breaking change: `jQuery.event.special` no longer inherits from `Object.prototype`
 
-This may affect code calling `hasOwnProperty` on `jQuery.event.special`, which should  be rare.
+This may affect code calling `hasOwnProperty` on `jQuery.event.special`, which should be rare.
 
 ### Manipulation
 
@@ -171,16 +219,31 @@ jQuery 4.0 adds support for [Trusted Types](https://developer.mozilla.org/en-US/
 
 This change was needed in order to add support for [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API). It's not entirely clear what real use cases might be affected by this change, but we're listing it here just in case.
 
-#### Important fix: Don't remove HTML comments from scripts
+#### Important fix: Don't remove HTML comments, including `CDATA` sections, from scripts
 
-Browsers can now handle this without jQuery's help. This change is not expected to affect existing code, but is an important fix because jQuery's logic removing those comments was not correctt in 100% of cases.
+Browsers can now handle this without jQuery's help. This change is not expected to affect existing code, but is an important fix because jQuery's logic removing those comments was not correct in 100% of cases.
 
 ### Selector
 
-#### Breaking change: Drop support for legacy pseudos
+#### Important fix: Backport jQuery selection context logic to selector-native
 
-References in Sizzle wiki: https://github.com/jquery/sizzle/wiki#-backwards-compatible-plugins-for-pseudos-with-arguments
+jQuery has long had a minimal selector engine that could be used in place of Sizzle. This engine was missing some logic that Sizzle had for handling the context of a selection. This change backports that logic to the native selector engine, which may affect code that relied on the old behavior. For example, `$div.find( "> *" )` will no longer throw an error when using the native selector engine.Also, given the following HTML:
 
-#### Important fix: Backport jQuery selection context logic to selector-native
+```html
+<div id="parent">
+	<span></span>
+</div>
+```
+
+The following returns 0 results in jQuery 4.0:
+
+```js
+const $div = $( "#parent" );
+$div.find( "div span" );
+```
 
-jQuery has long had a minimal selector engine that could be used in place of Sizzle. This engine was missing some logic that Sizzle had for handling the context of a selection. This change backports that logic to the native selector engine, which may affect code that relied on the old behavior. For example, `$div.find( "> *" )` will no longer throw an error when using the native selector engine.
+This is generally the expected behavior.
+
+#### Breaking change: Drop support for legacy custom pseudos
+
+References in Sizzle wiki: https://github.com/jquery/sizzle/wiki#-backwards-compatible-plugins-for-pseudos-with-arguments