init

2026-01-20 23:07:17 -05:00
commit e40bb35437
1 changed files with 870 additions and 0 deletions
@@ -0,0 +1,870 @@
+# jQuery 4.0.0 Documentation
+
+**Release Date:** January 17, 2026
+**License:** MIT
+**20th Anniversary Release**
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Browser Support](#browser-support)
+4. [Breaking Changes](#breaking-changes)
+5. [New Features](#new-features)
+6. [Migration Guide](#migration-guide)
+7. [API Reference](#api-reference)
+
+---
+
+## Overview
+
+jQuery 4.0.0 marks a significant milestone—celebrating jQuery's 20th anniversary and the first major version release in nearly 10 years. This release modernizes the library by removing legacy browser support, adopting ES modules, and improving security features.
+
+### Key Highlights
+
+- **Modernized codebase** migrated from AMD to ES modules
+- **Smaller bundle size** with improved slim build
+- **Enhanced security** with Trusted Types and CSP support
+- **Removed deprecated APIs** in favor of native JavaScript equivalents
+- **Updated browser support** dropping legacy browsers
+
+---
+
+## Installation
+
+### CDN
+
+```html
+<!-- Full version -->
+<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
+
+<!-- Slim version (no Deferreds/Callbacks, ~8kb smaller) -->
+<script src="https://code.jquery.com/jquery-4.0.0.slim.min.js"></script>
+```
+
+### npm
+
+```bash
+npm install jquery@4.0.0
+```
+
+### ES Module Import
+
+```javascript
+// Full import
+import $ from 'jquery';
+
+// Named import
+import { jQuery } from 'jquery';
+```
+
+### CommonJS
+
+```javascript
+const $ = require('jquery');
+```
+
+---
+
+## Browser Support
+
+### Supported Browsers
+
+| Browser | Minimum Version |
+|---------|-----------------|
+| Chrome | Last 3 versions |
+| Firefox | Last 2 versions + ESR |
+| Safari | Last 3 versions |
+| Edge (Chromium) | Last 3 versions |
+| iOS Safari | Last 3 versions |
+| Android Chrome | Last 3 versions |
+
+### Removed Support
+
+The following browsers are **no longer supported**:
+
+- Internet Explorer 10 and earlier (IE 11 support planned for removal in jQuery 5.0)
+- Edge Legacy (non-Chromium)
+- iOS versions older than the last 3
+- Firefox versions older than the last 2 (except ESR)
+- Android Browser (AOSP)
+
+---
+
+## Breaking Changes
+
+### 1. Removed Deprecated Utility Functions
+
+Several utility functions deprecated in previous versions have been removed. Use native JavaScript equivalents instead.
+
+| Removed Function | Native Replacement |
+|------------------|-------------------|
+| `jQuery.isArray()` | `Array.isArray()` |
+| `jQuery.parseJSON()` | `JSON.parse()` |
+| `jQuery.trim()` | `String.prototype.trim()` |
+| `jQuery.type()` | `typeof` / `instanceof` |
+| `jQuery.now()` | `Date.now()` |
+| `jQuery.isNumeric()` | `!isNaN(parseFloat(n)) && isFinite(n)` |
+| `jQuery.isFunction()` | `typeof fn === 'function'` |
+| `jQuery.isWindow()` | `obj != null && obj === obj.window` |
+
+#### Example Migration
+
+```javascript
+// jQuery 3.x (deprecated)
+if ($.isArray(myVar)) { /* ... */ }
+if ($.isFunction(callback)) { /* ... */ }
+var trimmed = $.trim(userInput);
+var data = $.parseJSON(jsonString);
+var timestamp = $.now();
+
+// jQuery 4.0 (use native)
+if (Array.isArray(myVar)) { /* ... */ }
+if (typeof callback === 'function') { /* ... */ }
+var trimmed = userInput.trim();
+var data = JSON.parse(jsonString);
+var timestamp = Date.now();
+```
+
+### 2. Focus Event Order Change
+
+The focus-related event order now follows the W3C specification.
+
+```javascript
+// jQuery 3.x order:
+// focusout → blur → focusin → focus
+
+// jQuery 4.0 order (W3C compliant):
+// blur → focusout → focus → focusin
+```
+
+#### Example: Observing Event Order
+
+```javascript
+const $input = $('#myInput');
+
+$input.on('blur', () => console.log('1. blur'));
+$input.on('focusout', () => console.log('2. focusout'));
+$input.on('focus', () => console.log('3. focus'));
+$input.on('focusin', () => console.log('4. focusin'));
+
+// When focus moves from #myInput to another element:
+// Output in jQuery 4.0:
+// 1. blur
+// 2. focusout
+// Then when new element receives focus:
+// 3. focus
+// 4. focusin
+```
+
+### 3. Removed Array Methods from jQuery Prototype
+
+The `push`, `sort`, and `splice` methods have been removed from the jQuery prototype.
+
+```javascript
+// jQuery 3.x
+$elements.push(newElement);
+$elements.sort(compareFn);
+$elements.splice(0, 1);
+
+// jQuery 4.0
+[].push.call($elements, newElement);
+[].sort.call($elements, compareFn);
+[].splice.call($elements, 0, 1);
+
+// Or convert to array first
+const elemArray = $elements.toArray();
+elemArray.push(newElement);
+```
+
+---
+
+## New Features
+
+### 1. ES Module Support
+
+jQuery 4.0 source has been migrated from AMD to ES modules, enabling better integration with modern build tools.
+
+#### Using with Modern Bundlers
+
+```javascript
+// Rollup, Webpack, Vite, etc.
+import $ from 'jquery';
+
+$(document).ready(() => {
+    console.log('jQuery 4.0 with ES modules!');
+});
+```
+
+#### Dynamic Import
+
+```javascript
+// Lazy load jQuery when needed
+async function initializeUI() {
+    const { default: $ } = await import('jquery');
+
+    $('.dynamic-content').fadeIn();
+}
+```
+
+### 2. Trusted Types Support
+
+jQuery 4.0 adds support for Trusted Types, enhancing security in environments with strict Content Security Policies.
+
+```javascript
+// jQuery now accepts TrustedHTML objects
+const policy = trustedTypes.createPolicy('myPolicy', {
+    createHTML: (string) => DOMPurify.sanitize(string)
+});
+
+const trustedContent = policy.createHTML('<p>Safe content</p>');
+$('#container').html(trustedContent);
+```
+
+### 3. Improved CSP Compatibility
+
+Async script requests now use `<script>` tags instead of inline scripts to avoid CSP violations.
+
+```javascript
+// Scripts loaded via $.getScript() now comply with CSP
+$.getScript('https://example.com/script.js')
+    .done(() => console.log('Script loaded (CSP compliant)'))
+    .fail(() => console.error('Script failed to load'));
+```
+
+### 4. Smaller Slim Build
+
+The slim build now excludes Deferreds and Callbacks, reducing the gzipped size by approximately 8kb.
+
+```html
+<!-- Regular: ~30kb gzipped -->
+<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
+
+<!-- Slim: ~19.5kb gzipped -->
+<script src="https://code.jquery.com/jquery-4.0.0.slim.min.js"></script>
+```
+
+**Slim build excludes:**
+- Ajax module
+- Effects/animation module
+- Deferreds
+- Callbacks
+
+---
+
+## Migration Guide
+
+### Using jQuery Migrate Plugin
+
+For gradual migration, use the jQuery Migrate plugin to identify deprecated features:
+
+```html
+<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
+<script src="https://code.jquery.com/jquery-migrate-4.0.0.min.js"></script>
+```
+
+The Migrate plugin will log warnings to the console for deprecated usage.
+
+### Step-by-Step Migration
+
+#### Step 1: Update Utility Function Calls
+
+```javascript
+// Before (jQuery 3.x)
+function processData(data) {
+    if ($.isArray(data)) {
+        return data.map(item => $.trim(item));
+    }
+    return $.trim(data);
+}
+
+// After (jQuery 4.0)
+function processData(data) {
+    if (Array.isArray(data)) {
+        return data.map(item => item.trim());
+    }
+    return data.trim();
+}
+```
+
+#### Step 2: Update Type Checking
+
+```javascript
+// Before (jQuery 3.x)
+function handleCallback(callback) {
+    if ($.isFunction(callback)) {
+        callback();
+    }
+}
+
+function getType(value) {
+    return $.type(value); // "array", "date", "regexp", etc.
+}
+
+// After (jQuery 4.0)
+function handleCallback(callback) {
+    if (typeof callback === 'function') {
+        callback();
+    }
+}
+
+function getType(value) {
+    if (Array.isArray(value)) return 'array';
+    if (value instanceof Date) return 'date';
+    if (value instanceof RegExp) return 'regexp';
+    return typeof value;
+}
+```
+
+#### Step 3: Handle Focus Event Order Changes
+
+```javascript
+// If your code depends on specific event order, update accordingly
+$('#form-field').on('focusout', function() {
+    // In jQuery 4.0, blur fires BEFORE focusout
+    // Adjust validation logic if needed
+    validateField(this);
+});
+```
+
+#### Step 4: Update Array Method Usage
+
+```javascript
+// Before (jQuery 3.x)
+const $items = $('.item');
+$items.push(document.createElement('div'));
+
+// After (jQuery 4.0) - Option 1: Use native call
+const $items = $('.item');
+[].push.call($items, document.createElement('div'));
+
+// After (jQuery 4.0) - Option 2: Use .add()
+const $items = $('.item').add(document.createElement('div'));
+```
+
+---
+
+## API Reference
+
+### Core Functions
+
+#### `jQuery(selector [, context])`
+
+Select elements from the DOM.
+
+```javascript
+// Select by ID
+const $header = $('#header');
+
+// Select by class
+const $buttons = $('.btn');
+
+// Select by tag
+const $paragraphs = $('p');
+
+// Select with context
+const $items = $('.item', '#container');
+
+// Create elements
+const $newDiv = $('<div class="new">Content</div>');
+```
+
+#### `jQuery.noConflict([removeAll])`
+
+Relinquish jQuery's control of the `$` variable.
+
+```javascript
+const jq = $.noConflict();
+jq('#element').addClass('active');
+
+// With removeAll=true, also removes 'jQuery' global
+const jq = jQuery.noConflict(true);
+```
+
+### Utilities
+
+#### `jQuery.extend([deep], target, object1 [, objectN])`
+
+Merge objects into the target object.
+
+```javascript
+// Shallow merge
+const defaults = { color: 'blue', size: 'medium' };
+const options = { color: 'red' };
+const settings = $.extend({}, defaults, options);
+// Result: { color: 'red', size: 'medium' }
+
+// Deep merge
+const obj1 = { a: { b: 1, c: 2 } };
+const obj2 = { a: { b: 3 } };
+const result = $.extend(true, {}, obj1, obj2);
+// Result: { a: { b: 3, c: 2 } }
+```
+
+#### `jQuery.each(collection, callback)`
+
+Iterate over arrays or objects.
+
+```javascript
+// Array iteration
+$.each(['a', 'b', 'c'], function(index, value) {
+    console.log(`${index}: ${value}`);
+});
+
+// Object iteration
+$.each({ name: 'John', age: 30 }, function(key, value) {
+    console.log(`${key}: ${value}`);
+});
+
+// Return false to break the loop
+$.each([1, 2, 3, 4, 5], function(i, num) {
+    if (num > 3) return false;
+    console.log(num);
+});
+// Output: 1, 2, 3
+```
+
+#### `jQuery.map(array, callback)`
+
+Transform array elements.
+
+```javascript
+const numbers = [1, 2, 3, 4];
+const doubled = $.map(numbers, n => n * 2);
+// Result: [2, 4, 6, 8]
+
+// Can return multiple values
+const expanded = $.map([1, 2], n => [n, n * 2]);
+// Result: [1, 2, 2, 4]
+
+// Return null to remove item
+const filtered = $.map([1, 2, 3, 4], n => n > 2 ? n : null);
+// Result: [3, 4]
+```
+
+#### `jQuery.grep(array, function [, invert])`
+
+Filter array elements.
+
+```javascript
+const numbers = [1, 2, 3, 4, 5, 6];
+
+// Keep elements where callback returns true
+const evens = $.grep(numbers, n => n % 2 === 0);
+// Result: [2, 4, 6]
+
+// With invert=true, keep elements where callback returns false
+const odds = $.grep(numbers, n => n % 2 === 0, true);
+// Result: [1, 3, 5]
+```
+
+#### `jQuery.merge(first, second)`
+
+Merge two arrays.
+
+```javascript
+const arr1 = [1, 2];
+const arr2 = [3, 4];
+$.merge(arr1, arr2);
+// arr1 is now [1, 2, 3, 4]
+
+// Works with array-like objects
+const $divs = $('div');
+const $spans = $('span');
+$.merge($divs, $spans);
+```
+
+#### `jQuery.inArray(value, array [, fromIndex])`
+
+Find value index in array.
+
+```javascript
+const arr = ['a', 'b', 'c', 'd'];
+
+$.inArray('b', arr);     // Returns: 1
+$.inArray('x', arr);     // Returns: -1
+$.inArray('b', arr, 2);  // Returns: -1 (starts search at index 2)
+```
+
+#### `jQuery.isPlainObject(obj)`
+
+Check if value is a plain object.
+
+```javascript
+$.isPlainObject({});              // true
+$.isPlainObject({ a: 1 });        // true
+$.isPlainObject(new Object());    // true
+
+$.isPlainObject([]);              // false
+$.isPlainObject(document.body);   // false
+$.isPlainObject(new Date());      // false
+```
+
+#### `jQuery.isEmptyObject(obj)`
+
+Check if object has no properties.
+
+```javascript
+$.isEmptyObject({});           // true
+$.isEmptyObject({ a: 1 });     // false
+$.isEmptyObject([]);           // true (arrays are objects)
+```
+
+### Callbacks Object
+
+#### `jQuery.Callbacks(flags)`
+
+Create a callback list with optional flags.
+
+**Flags:**
+- `once`: Callbacks fire only once
+- `memory`: Remember previous values and call new callbacks immediately
+- `unique`: Prevent duplicate callbacks
+- `stopOnFalse`: Stop firing when a callback returns false
+
+```javascript
+// Basic usage
+const callbacks = $.Callbacks();
+
+function fn1(value) {
+    console.log('fn1:', value);
+}
+
+function fn2(value) {
+    console.log('fn2:', value);
+}
+
+callbacks.add(fn1);
+callbacks.add(fn2);
+callbacks.fire('hello');
+// Output:
+// fn1: hello
+// fn2: hello
+
+// With flags
+const onceCallbacks = $.Callbacks('once');
+onceCallbacks.add(fn1);
+onceCallbacks.fire('first');   // fn1: first
+onceCallbacks.fire('second');  // (nothing - already fired)
+
+// Memory flag - useful for ready-like patterns
+const memoryCallbacks = $.Callbacks('memory');
+memoryCallbacks.fire('done');
+memoryCallbacks.add(fn1);  // Immediately called with 'done'
+```
+
+### Deferred Object
+
+#### `jQuery.Deferred([beforeStart])`
+
+Create a Deferred object for async operations.
+
+```javascript
+function asyncOperation() {
+    const deferred = $.Deferred();
+
+    setTimeout(() => {
+        const success = Math.random() > 0.5;
+
+        if (success) {
+            deferred.resolve('Operation succeeded');
+        } else {
+            deferred.reject('Operation failed');
+        }
+    }, 1000);
+
+    return deferred.promise();
+}
+
+asyncOperation()
+    .done(result => console.log(result))
+    .fail(error => console.error(error))
+    .always(() => console.log('Complete'));
+```
+
+#### `jQuery.when(deferreds)`
+
+Execute callback when all Deferreds resolve.
+
+```javascript
+function fetchUser() {
+    return $.ajax('/api/user');
+}
+
+function fetchPosts() {
+    return $.ajax('/api/posts');
+}
+
+$.when(fetchUser(), fetchPosts())
+    .done((userData, postsData) => {
+        console.log('User:', userData[0]);
+        console.log('Posts:', postsData[0]);
+    })
+    .fail(() => {
+        console.error('One or more requests failed');
+    });
+```
+
+### DOM Ready
+
+#### `jQuery(callback)` / `jQuery.ready`
+
+Execute code when DOM is ready.
+
+```javascript
+// Shorthand (recommended)
+$(function() {
+    console.log('DOM ready');
+});
+
+// Explicit ready
+$(document).ready(function() {
+    console.log('DOM ready');
+});
+
+// Arrow function
+$(() => {
+    console.log('DOM ready');
+});
+
+// Multiple ready handlers are executed in order
+$(() => console.log('First'));
+$(() => console.log('Second'));
+```
+
+### Data Storage
+
+#### `.data(key, value)` / `.data(key)` / `.data()`
+
+Store and retrieve data associated with elements.
+
+```javascript
+// Set data
+$('#element').data('userId', 123);
+$('#element').data('config', { theme: 'dark', lang: 'en' });
+
+// Get data
+const userId = $('#element').data('userId');  // 123
+const config = $('#element').data('config');  // { theme: 'dark', lang: 'en' }
+
+// Get all data
+const allData = $('#element').data();
+// { userId: 123, config: { theme: 'dark', lang: 'en' } }
+
+// HTML5 data attributes are auto-loaded
+// <div id="user" data-user-id="456" data-role="admin">
+$('#user').data('userId');  // 456
+$('#user').data('role');    // 'admin'
+```
+
+#### `.removeData(key)`
+
+Remove stored data.
+
+```javascript
+$('#element').data('temp', 'value');
+$('#element').removeData('temp');
+
+// Remove all data
+$('#element').removeData();
+```
+
+### Traversal
+
+#### `.find(selector)`
+
+Find descendant elements.
+
+```javascript
+// Find all paragraphs inside #content
+$('#content').find('p').addClass('styled');
+
+// Chained traversal
+$('#nav')
+    .find('li')
+    .find('a')
+    .addClass('nav-link');
+```
+
+#### `.filter(selector)` / `.filter(function)`
+
+Reduce matched elements.
+
+```javascript
+// Filter by selector
+$('li').filter('.active').css('font-weight', 'bold');
+
+// Filter by function
+$('input').filter(function() {
+    return $(this).val().length > 0;
+}).addClass('has-value');
+
+// Filter with index
+$('tr').filter(':even').addClass('striped');
+```
+
+#### `.closest(selector)`
+
+Find closest ancestor matching selector.
+
+```javascript
+// Find parent form
+$('input').on('blur', function() {
+    const $form = $(this).closest('form');
+    validateForm($form);
+});
+
+// With context
+$('.item').closest('.container', '#wrapper');
+```
+
+#### `.has(selector)`
+
+Filter elements that have matching descendants.
+
+```javascript
+// Only select divs that contain a span
+$('div').has('span').addClass('has-span');
+
+// Select list items with links
+$('li').has('a').css('background', '#f0f0f0');
+```
+
+#### `.index([selector | element])`
+
+Get element index.
+
+```javascript
+// Index among siblings
+$('li.active').index();  // Position among siblings
+
+// Index in jQuery collection
+const $items = $('li');
+$items.index($('.active'));  // Position in collection
+
+// With selector
+$('li').index('li.active');  // Find index of .active among all li
+```
+
+#### `.add(selector)`
+
+Add elements to the matched set.
+
+```javascript
+// Combine selections
+$('p')
+    .add('span')
+    .add('div.highlight')
+    .addClass('styled');
+
+// Add newly created element
+$('.existing').add('<p>New paragraph</p>').appendTo('#container');
+```
+
+#### `.addBack([selector])`
+
+Add previous set to current set.
+
+```javascript
+// Select all children and the parent
+$('#parent')
+    .find('> *')
+    .addBack()
+    .addClass('highlighted');
+
+// With filter
+$('ul')
+    .find('li')
+    .addBack('ul.main')
+    .css('border', '1px solid');
+```
+
+### DOM Evaluation
+
+#### `jQuery.DOMEval(code, options)`
+
+Safely execute script code with nonce support (internal use, enhanced in 4.0).
+
+```javascript
+// jQuery internally uses this for script execution
+// Preserves nonce attributes for CSP compliance
+// Handles type, src, nonce, and noModule attributes
+```
+
+---
+
+## Security Features
+
+### Prototype Pollution Prevention
+
+jQuery 4.0 includes protection against prototype pollution attacks in `$.extend()`:
+
+```javascript
+// These attempts are blocked
+$.extend(true, {}, JSON.parse('{"__proto__": {"polluted": true}}'));
+$.extend(true, {}, { constructor: { prototype: { polluted: true } } });
+
+// Object.prototype remains unpolluted
+console.log({}.polluted);  // undefined
+```
+
+### XSS Mitigation
+
+The selector engine escapes special characters to prevent XSS:
+
+```javascript
+// Safe selector escaping
+const userInput = 'div"><script>alert("xss")</script>';
+const escaped = $.escapeSelector(userInput);
+// Safely escaped for use in selectors
+```
+
+### CSP Compliance
+
+Script loading now complies with Content Security Policy:
+
+```javascript
+// Scripts are loaded via <script> tags, not eval()
+$.getScript('/trusted/script.js');
+
+// Works with strict CSP headers:
+// Content-Security-Policy: script-src 'self'
+```
+
+---
+
+## Changelog Summary
+
+### Added
+- ES module support for modern build tools
+- Trusted Types support for enhanced security
+- CSP-compliant script loading
+- Improved slim build (8kb smaller)
+
+### Removed
+- IE 10 and earlier support
+- Edge Legacy support
+- `jQuery.isArray()`, `jQuery.parseJSON()`, `jQuery.trim()`, `jQuery.type()`
+- `jQuery.now()`, `jQuery.isNumeric()`, `jQuery.isFunction()`, `jQuery.isWindow()`
+- `push`, `sort`, `splice` from jQuery prototype
+
+### Changed
+- Focus event order now follows W3C specification
+- Source migrated from AMD to ES modules
+
+---
+
+## Resources
+
+- **Official Website:** [jquery.com](https://jquery.com)
+- **Documentation:** [api.jquery.com](https://api.jquery.com)
+- **GitHub:** [github.com/jquery/jquery](https://github.com/jquery/jquery)
+- **npm:** [npmjs.com/package/jquery](https://www.npmjs.com/package/jquery)
+- **CDN:** [code.jquery.com](https://code.jquery.com)
+- **Migration Plugin:** [github.com/jquery/jquery-migrate](https://github.com/jquery/jquery-migrate)
+
+---
+
+*Documentation generated for jQuery 4.0.0 (January 2026)*