From 2ae509e7e733c3e752b9524aded3cfffc6f64a2f Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Fri, 28 Jun 2024 14:47:00 -0700 Subject: [PATCH] Update doc comments, bump version to 1.0.0-wip (#268) --- CHANGELOG.md | 2 +- lib/src/dom/clipboard_apis.dart | 9 + lib/src/dom/css_conditional.dart | 2 +- lib/src/dom/css_view_transitions.dart | 52 ++-- lib/src/dom/cssom.dart | 21 +- lib/src/dom/dom.dart | 189 +++++++++------ lib/src/dom/encrypted_media.dart | 86 +++---- lib/src/dom/fetch.dart | 7 + lib/src/dom/fileapi.dart | 20 +- lib/src/dom/geolocation.dart | 4 + lib/src/dom/html.dart | 327 +++++++++++++++++--------- lib/src/dom/indexeddb.dart | 11 + lib/src/dom/mathml_core.dart | 19 ++ lib/src/dom/navigation_timing.dart | 2 +- lib/src/dom/service_workers.dart | 16 +- lib/src/dom/storage.dart | 4 +- lib/src/dom/svg.dart | 28 +++ lib/src/dom/touch_events.dart | 20 +- lib/src/dom/uievents.dart | 43 ++-- lib/src/dom/url.dart | 24 +- lib/src/dom/webaudio.dart | 24 +- lib/src/dom/webcryptoapi.dart | 4 +- lib/src/dom/webrtc.dart | 33 +-- pubspec.yaml | 2 +- third_party/mdn/mdn.json | 280 +++++++++++++--------- 25 files changed, 783 insertions(+), 446 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b9cdd1ab..12970d2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## 0.6.0-wip +## 1.0.0-wip - Added supertypes' fields to dictionary constructors as dictionaries are allowed to contain those fields. diff --git a/lib/src/dom/clipboard_apis.dart b/lib/src/dom/clipboard_apis.dart index 2ad520a0..6528a96c 100644 --- a/lib/src/dom/clipboard_apis.dart +++ b/lib/src/dom/clipboard_apis.dart @@ -83,6 +83,15 @@ extension type ClipboardItem._(JSObject _) implements JSObject { ClipboardItemOptions options, ]); + /// The **`supports()`** static method of the [ClipboardItem] interface + /// returns `true` if the given is supported by the clipboard, and `false` + /// otherwise. + /// + /// Note that the + /// [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) + /// mandates support for plain text, HTML and PNG files. + /// The `supports()` method will always return `true` for these MIME types, so + /// testing them is unnecessary . external static bool supports(String type); /// The **`getType()`** method of the [ClipboardItem] interface returns a diff --git a/lib/src/dom/css_conditional.dart b/lib/src/dom/css_conditional.dart index 062fe593..692640ed 100644 --- a/lib/src/dom/css_conditional.dart +++ b/lib/src/dom/css_conditional.dart @@ -29,7 +29,7 @@ import 'cssom.dart'; /// [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/CSSConditionRule). extension type CSSConditionRule._(JSObject _) implements CSSGroupingRule, JSObject { - /// The **`conditionText`** property of + /// The read-only **`conditionText`** property of /// the [CSSConditionRule] interface returns or sets the text of the CSS /// rule. external String get conditionText; diff --git a/lib/src/dom/css_view_transitions.dart b/lib/src/dom/css_view_transitions.dart index 19ffa14d..599b147f 100644 --- a/lib/src/dom/css_view_transitions.dart +++ b/lib/src/dom/css_view_transitions.dart @@ -16,14 +16,22 @@ import 'dart:js_interop'; typedef UpdateCallback = JSFunction; /// The **`ViewTransition`** interface of the [View Transitions API] represents -/// a view transition, and provides functionality to react to the transition -/// reaching different states (e.g. ready to run the animation, or animation -/// finished) or skip the transition altogether. +/// an active view transition, and provides functionality to react to the +/// transition reaching different states (e.g. ready to run the animation, or +/// animation finished) or skip the transition altogether. /// -/// This object type is returned by the [Document.startViewTransition] method. -/// When `startViewTransition()` is invoked, a sequence of steps is followed as -/// explained in -/// [The view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). +/// This object type is made available in the following ways: +/// +/// - In the case of same-document (SPA) transitions, it is returned by the +/// [Document.startViewTransition] method. +/// - In the case of cross-document (MPA) transitions, it is made available: +/// - In the outgoing page via the [Window.pageswap_event] event object's [PageSwapEvent.viewTransition] property. +/// - In the inbound page via the [Window.pagereveal_event] event object's [PageRevealEvent.viewTransition] property. +/// +/// When a view transition is triggered by a `startViewTransition()` call (or a +/// page navigation in the case of MPA transitions), a sequence of steps is +/// followed as explained in +/// [The view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API/Using#the_view_transition_process). /// This also explains when the different promises fulfill. /// /// --- @@ -33,18 +41,21 @@ typedef UpdateCallback = JSFunction; extension type ViewTransition._(JSObject _) implements JSObject { /// The **`skipTransition()`** method of the /// [ViewTransition] interface skips the animation part of the view - /// transition, but doesn't skip running the [Document.startViewTransition] - /// callback that updates the DOM. + /// transition, but doesn't skip running the associated view update. external void skipTransition(); /// The **`updateCallbackDone`** read-only property of the /// [ViewTransition] interface is a `Promise` that fulfills when the promise - /// returned by the [Document.startViewTransition]'s callback fulfills, or - /// rejects when it rejects. + /// returned by the [Document.startViewTransition] method's callback fulfills, + /// or rejects when it rejects. /// /// `updateCallbackDone` is useful when you don't care about the - /// success/failure of the transition animation, and just want to know if and - /// when the DOM is updated. + /// success/failure of a same-document (SPA) view transition animation, and + /// just want to know if and when the DOM is updated. + /// + /// > **Note:** In the case of a cross-document (MPA) view transition, the + /// > `updateCallbackDone` promise of the associated `ViewTransition` is + /// > automatically fulfilled. external JSPromise get updateCallbackDone; /// The **`ready`** read-only property of the @@ -53,7 +64,7 @@ extension type ViewTransition._(JSObject _) implements JSObject { /// start. /// /// `ready` will reject if the transition cannot begin. This can be due to - /// misconfiguration, for example duplicate s, or if the callback passed to + /// misconfiguration, for example, duplicate s, or if the callback passed to /// [Document.startViewTransition] throws or returns a promise that rejects. external JSPromise get ready; @@ -62,12 +73,13 @@ extension type ViewTransition._(JSObject _) implements JSObject { /// transition animation is finished, and the new page view is visible and /// interactive to the user. /// - /// `finished` only rejects if the callback passed to - /// [Document.startViewTransition]throws or returns a promise that rejects, - /// which indicates that the new state of the page wasn't created. + /// `finished` will only reject in the case of a same-document (SPA) + /// transition, if the callback passed to [Document.startViewTransition] + /// throws or returns a promise that rejects. This would indicate that the new + /// state of the page wasn't created. /// - /// If a transition animation fails to start, or is skipped during the - /// animation using [ViewTransition.skipTransition], the end state is still - /// reached therefore `finished` still fulfills. + /// If a transition animation fails to start or is skipped during the + /// transition using [ViewTransition.skipTransition], the end state is still + /// reached therefore `finished` will still fulfill. external JSPromise get finished; } diff --git a/lib/src/dom/cssom.dart b/lib/src/dom/cssom.dart index 98cf3037..ff7de5bb 100644 --- a/lib/src/dom/cssom.dart +++ b/lib/src/dom/cssom.dart @@ -296,16 +296,19 @@ extension type StyleSheetList._(JSObject _) implements JSObject { /// [CSSStyleSheet.insertRule] and [CSSStyleSheet.deleteRule], which are methods /// of [CSSStyleSheet]. /// -/// The interface has no constructor. An instance of `CSSRuleList` is returned -/// by [CSSStyleSheet.cssRules] and [CSSKeyframesRule.cssRules]. +/// This interface was an +/// [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) +/// and only continues to be supported to not break code that's already using +/// it. Modern APIs represent list structures using types based on JavaScript +/// [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), +/// thus making many array methods available, and at the same time imposing +/// additional semantics on their usage (such as making their items read-only). /// -/// > **Note:** This interface was an -/// > [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) -/// > and only continues to be supported to not break code that's already using -/// > it. Modern APIs use types that wrap around ECMAScript array types instead, -/// > so you can treat them like ECMAScript arrays, and at the same time impose -/// > additional semantics on their usage (such as making their items -/// > read-only). +/// These historical reasons do not mean that you as a developer should avoid +/// `CSSRuleList`. You don't create `CSSRuleList` objects yourself, but you get +/// them from APIs such as [CSSStyleSheet.cssRules] and +/// [CSSKeyframesRule.cssRules], and these APIs are not deprecated. However, be +/// careful of the semantic differences from a real array. /// /// --- /// diff --git a/lib/src/dom/dom.dart b/lib/src/dom/dom.dart index 2d5dec5a..aabcb258 100644 --- a/lib/src/dom/dom.dart +++ b/lib/src/dom/dom.dart @@ -183,6 +183,12 @@ extension type Event._(JSObject _) implements JSObject { /// [bubbled](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling) /// up to the element with the handler. The element on which the event was /// fired is given by [Event.target]. + /// + /// Note that the value of `currentTarget` is only available in a handler for + /// the event. Outside an event handler it will be `null`. This means that, + /// for example, if you take a reference to the `Event` object inside an event + /// handler and then access its `currentTarget` property outside the event + /// handler, its value will be `null`. external EventTarget? get currentTarget; /// The **`eventPhase`** read-only property of the @@ -279,10 +285,12 @@ extension type Event._(JSObject _) implements JSObject { /// The **`isTrusted`** read-only property of the /// [Event] interface is a boolean value that is `true` - /// when the event was generated by a user action, and `false` when the event - /// was - /// created or modified by a script or dispatched via + /// when the event was generated by the user agent (including via user actions + /// and programmatic methods such as [HTMLElement.focus]), + /// and `false` when the event was dispatched via /// [EventTarget.dispatchEvent]. + /// The only exception is the `click` event, which initializes the `isTrusted` + /// property to `false` in user agents. external bool get isTrusted; /// The **`timeStamp`** read-only property of the [Event] interface returns @@ -641,9 +649,23 @@ extension type AbortSignal._(JSObject _) implements EventTarget, JSObject { /// returned by properties such as [Node.childNodes] and methods such as /// [document.querySelectorAll]. /// -/// > **Note:** Although `NodeList` is not an `Array`, it is possible to iterate -/// > over it with `forEach()`. It can also be converted to a real `Array` using -/// > `Array.from()`. +/// This interface was an +/// [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) +/// and only continues to be supported to not break code that's already using +/// it. Modern APIs represent list structures using types based on JavaScript +/// [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), +/// thus making many array methods available, and at the same time imposing +/// additional semantics on their usage (such as making their items read-only). +/// +/// These historical reasons do not mean that you as a developer should avoid +/// `NodeList`. You don't create `NodeList` objects yourself, but you get them +/// from APIs such as [Document.querySelectorAll], and these APIs are not +/// deprecated. However, be careful of the semantic differences from a real +/// array. +/// +/// Although `NodeList` is not an `Array`, it is possible to iterate over it +/// with `forEach()`. It can also be converted to a real `Array` using +/// `Array.from()`. /// /// --- /// @@ -669,22 +691,28 @@ extension type NodeList._(JSObject _) implements JSObject { /// (array-like object similar to `arguments`) of elements (in document order) /// and offers methods and properties for selecting from the list. /// -/// > **Note:** This interface is called `HTMLCollection` for historical reasons -/// > (before the modern DOM, collections implementing this interface could only -/// > have HTML elements as their items). -/// /// An `HTMLCollection` in the HTML DOM is live; it is automatically updated /// when the underlying document is changed. For this reason it is a good idea /// to make a copy (e.g., using `Array.from`) to iterate over if adding, moving, /// or removing nodes. /// -/// > **Note:** This interface was an -/// > [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) -/// > and only continues to be supported to not break code that's already using -/// > it. Modern APIs use types that wrap around ECMAScript array types instead, -/// > so you can treat them like ECMAScript arrays, and at the same time impose -/// > additional semantics on their usage (such as making their items -/// > read-only). +/// This interface is called `HTMLCollection` for historical reasons, because +/// before the modern DOM, collections implementing this interface could only +/// have HTML elements as their items. +/// +/// This interface was an +/// [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) +/// and only continues to be supported to not break code that's already using +/// it. Modern APIs represent list structures using types based on JavaScript +/// [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), +/// thus making many array methods available, and at the same time imposing +/// additional semantics on their usage (such as making their items read-only). +/// +/// These historical reasons do not mean that you as a developer should avoid +/// `HTMLCollection`. You don't create `HTMLCollection` objects yourself, but +/// you get them from APIs such as [Document.getElementsByClassName], and these +/// APIs are not deprecated. However, be careful of the semantic differences +/// from a real array. /// /// --- /// @@ -1268,7 +1296,7 @@ external Document get document; /// The **`Document`** interface represents any web page loaded in the browser /// and serves as an entry point into the web page's content, which is the -/// [DOM tree](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Using_the_Document_Object_Model#what_is_a_dom_tree). +/// [DOM tree](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Using_the_Document_Object_Model#what_is_a_dom_tree). /// /// The DOM tree includes elements such as `body` and `table`, among /// [many others](https://developer.mozilla.org/en-US/docs/Web/HTML/Element). It @@ -1290,15 +1318,30 @@ external Document get document; extension type Document._(JSObject _) implements Node, JSObject { external factory Document(); + /// The **`parseHTMLUnsafe()`** static method of the [Document] object is used + /// to parse a string of HTML, which may contain + /// [declarative shadow roots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom), + /// in order to create a new [Document] instance. + /// + /// The suffix "Unsafe" in the method name indicates that, while `\n \n\n```\n\n### Use of `target` and `relatedTarget`\n\nThe `relatedTarget` property for the `mouseover` event holds the node that the mouse was previously over. For the `mouseout` event, it holds the node that the mouse moved to.\n\n| Event type | [event.target](https://developer.mozilla.org/en-US/docs/Web/API/Event/target) | [event.relatedTarget](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/relatedTarget) |\n| ----------- | ------------------------------------------------- | ------------------------------------------------------------------- |\n| `mouseover` | the EventTarget which the pointing device entered | the EventTarget which the pointing device exited |\n| `mouseout` | the EventTarget which the pointing device exited | the EventTarget which the pointing device entered |\n\n#### Example\n\n```xml\n\n ' + event.target.id + '\\n');\"\n onmouseout=\"console.log('mouseout ' + event.target.id + ' > ' + event.relatedTarget.id + '\\n');\"\n style=\"margin: 100px; border: 10px solid black; width: 100px; height: 100px;\" />\n\n```", + "comparison_of_event_targets": "It's easy to get confused about which event target to examine when writing an event handler. This article should clarify the use of the target properties.\n\nThere are five targets to consider:\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
PropertyDefined inPurpose
\n event.target\n \n DOM Event Interface\n \n The DOM element on the left-hand side of the call that triggered this event.\n
\n event.currentTarget\n \n DOM Event Interface\n \n The EventTarget whose EventListeners are currently being processed. As the event capturing and bubbling occurs, this value changes.\n
\n event.relatedTarget\n \n DOM MouseEvent Interface\n Identifies a secondary target for the event.
\n event.explicitOriginalTarget\n \n Event.webidl\n \n If the event was retargeted for some reason other than an anonymous boundary crossing, this will be set to the target before the retargeting occurs. For example, mouse events are retargeted to their parent node when they happen over text nodes ([Firefox bug 185889](https://bugzil.la/185889)), and in that case .target will show the parent and .explicitOriginalTarget will show the text node.
\n Unlike .originalTarget, .explicitOriginalTarget will never contain anonymous content.\n
\n event.originalTarget\n \n Event.webidl\n \n The original target of the event, before any retargetings.\n
event.composedTarget\n Event.webidl\n \n The original non-native target of the event before composition from Shadow DOM.\n
\n\n### Use of `explicitOriginalTarget` and `originalTarget`\n\n> **Note:** These properties are only available in Mozilla-based browsers.\n\n### Examples\n\n```html\n\n\n \n \n \n Comparison of Event Targets\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n Original target dispatching the event event.target\n \n Target who's event listener is being processed\n event.currentTarget\n \n Identify other element (if any) involved in the event\n event.relatedTarget\n \n If there was a retargeting of the event for some reason\n event.explicitOriginalTarget contains the target\n before retargeting (never contains anonymous targets)\n \n If there was a retargeting of the event for some reason\n event.originalTarget contains the target before\n retargeting (may contain anonymous targets)\n
\n

\n Clicking on the text will show the difference between\n explicitOriginalTarget, originalTarget, and target\n

\n \n \n\n```\n\n### Use of `target` and `relatedTarget`\n\nThe `relatedTarget` property for the `mouseover` event holds the node that the mouse was previously over. For the `mouseout` event, it holds the node that the mouse moved to.\n\n| Event type | [event.target](https://developer.mozilla.org/en-US/docs/Web/API/Event/target) | [event.relatedTarget](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/relatedTarget) |\n| ----------- | ------------------------------------------------- | ------------------------------------------------------------------- |\n| `mouseover` | the EventTarget which the pointing device entered | the EventTarget which the pointing device exited |\n| `mouseout` | the EventTarget which the pointing device exited | the EventTarget which the pointing device entered |\n\n#### Example\n\n```xml\n\n ' + event.target.id + '\\n');\"\n onmouseout=\"console.log('mouseout ' + event.target.id + ' > ' + event.relatedTarget.id + '\\n');\"\n style=\"margin: 100px; border: 10px solid black; width: 100px; height: 100px;\" />\n\n```", "composed": "The read-only **`composed`** property of the\n[Event] interface returns a boolean value which indicates whether\nor not the event will propagate across the shadow DOM boundary into the standard DOM.\n\nAll UA-dispatched UI events are composed (click/touch/mouseover/copy/paste, etc.). Most\nother types of events are not composed, and so will return `false`. For\nexample, this includes synthetic events that are created without their\n`composed` option set to `true`.\n\nPropagation only occurs if the [Event.bubbles] property is also\n`true`. However, capturing only composed events are also handled at host as\nif they were in `AT_TARGET` phase. You can determine the path the event will\nfollow through the shadow root to the DOM root by calling\n[Event.composedPath].", "composedpath": "The **`composedPath()`** method of the [Event]\ninterface returns the event's path which is an array of the objects on which listeners\nwill be invoked. This does not include nodes in shadow trees if the shadow root was\ncreated with its [ShadowRoot.mode] closed.", - "currenttarget": "The **`currentTarget`** read-only property of the [Event] interface identifies the element to which the event handler has been attached.\n\nThis will not always be the same as the element on which the event was fired, because the event may have fired on a descendant of the element with the handler, and then [bubbled](/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling) up to the element with the handler. The element on which the event was fired is given by [Event.target].", + "currenttarget": "The **`currentTarget`** read-only property of the [Event] interface identifies the element to which the event handler has been attached.\n\nThis will not always be the same as the element on which the event was fired, because the event may have fired on a descendant of the element with the handler, and then [bubbled](/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling) up to the element with the handler. The element on which the event was fired is given by [Event.target].\n\nNote that the value of `currentTarget` is only available in a handler for the event. Outside an event handler it will be `null`. This means that, for example, if you take a reference to the `Event` object inside an event handler and then access its `currentTarget` property outside the event handler, its value will be `null`.", "defaultprevented": "The **`defaultPrevented`** read-only property of the [Event] interface returns a boolean value indicating whether or not the call to [Event.preventDefault] canceled the event.", "event": "The **`Event()`** constructor creates a new [Event] object. An event created in this way is called a _synthetic event_, as opposed to an event fired by the browser, and can be [dispatched](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) by a script.", "eventphase": "The **`eventPhase`** read-only property of the\n[Event] interface indicates which phase of the event flow is currently\nbeing evaluated.", "explicitoriginaltarget": "The read-only **`explicitOriginalTarget`** property of the [Event] interface returns the non-anonymous original target of the event.\n\nIf the event was retargeted for some reason other than an anonymous boundary crossing, this will be set to the target before the retargeting occurs.\n\nFor example, mouse events are retargeted to their parent node when they happen over text nodes (see [Firefox bug 185889](https://bugzil.la/185889)), and in that case [`currentTarget`](https://developer.mozilla.org/en-US/docs/Web/API/Event/currentTarget) will show the parent while this property will show the text node.\n\nThis property also differs from [`originalTarget`](https://developer.mozilla.org/en-US/docs/Web/API/Event/originalTarget) in that it will never contain anonymous content.", "initevent": "The **`Event.initEvent()`** method is used to initialize the\nvalue of an [event] created using [Document.createEvent].\n\nEvents initialized in this way must have been created with the\n[Document.createEvent] method.\nThis method must be called to set the event\nbefore it is dispatched, using [EventTarget.dispatchEvent].\nOnce dispatched, it doesn't do anything anymore.\n\n> **Note:** _Do not use this method anymore as it is deprecated._\n> Instead use specific event constructors, like [Event.Event].\n> The page on [Creating and triggering events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) gives more information about the way to use these.", - "istrusted": "The **`isTrusted`** read-only property of the\n[Event] interface is a boolean value that is `true`\nwhen the event was generated by a user action, and `false` when the event was\ncreated or modified by a script or dispatched via\n[EventTarget.dispatchEvent].", + "istrusted": "The **`isTrusted`** read-only property of the\n[Event] interface is a boolean value that is `true`\nwhen the event was generated by the user agent (including via user actions and programmatic methods such as [HTMLElement.focus]),\nand `false` when the event was dispatched via\n[EventTarget.dispatchEvent].\nThe only exception is the `click` event, which initializes the `isTrusted`\nproperty to `false` in user agents.", "originaltarget": "The read-only **`originalTarget`** property of the [Event] interface returns the original target of the event before any retargetings. Unlike [Event.explicitOriginalTarget] it can also be native anonymous content.\n\nSee also [Comparison of Event Targets](https://developer.mozilla.org/en-US/docs/Web/API/Event/Comparison_of_Event_Targets).", "preventdefault": "The **`preventDefault()`** method of the [Event] interface tells the that if the event does not get explicitly handled, its default action should not be taken as it normally would be.\n\nThe event continues to propagate as usual,\nunless one of its event listeners calls\n[Event.stopPropagation]\nor [Event.stopImmediatePropagation],\neither of which terminates propagation at once.\n\nAs noted below, calling **`preventDefault()`** for a\nnon-cancelable event, such as one dispatched via\n[EventTarget.dispatchEvent], without specifying\n`cancelable: true` has no effect.", "returnvalue": "The [Event] property\n**`returnValue`** indicates whether the default action for\nthis event has been prevented or not.\n\nIt is set to `true` by\ndefault, allowing the default action to occur. Setting this property to\n`false` prevents the default action.\n\n> **Note:** While `returnValue` has been adopted into the DOM\n> standard, it is present primarily to support existing code. Use\n> [Event.preventDefault], and\n> [Event.defaultPrevented] instead of this historical\n> property.", @@ -2458,7 +2462,7 @@ "docs": "The `FileEntrySync` interface represents a file in a file system. It lets you write content to a file.\n\n> **Warning:** This interface is deprecated and is no more on the standard track.\n> _Do not use it anymore._ Use the [File and Directory Entries API](https://developer.mozilla.org/en-US/docs/Web/API/File_and_Directory_Entries_API) instead." }, "FileList": { - "docs": "The **`FileList`** interface represents an object of this type returned by the `files` property of the HTML `input` element; this lets you access the list of files selected with the `` element. It's also used for a list of files dropped into web content when using the drag and drop API; see the [DataTransfer] object for details on this usage.\n\nAll `` element nodes have a `files` attribute of type `FileList` on them which allows access to the items in this list. For example, if the HTML includes the following file input:\n\n```html\n\n```\n\nThe following line of code fetches the first file in the node's file list as a [File] object:\n\n```js\nconst file = document.getElementById(\"fileItem\").files[0];\n```\n\n> **Note:** This interface was an [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) and only continues to be supported to not break code that's already using it. Modern APIs use types that wrap around ECMAScript array types instead, so you can treat them like ECMAScript arrays, and at the same time impose additional semantics on their usage (such as making their items read-only).", + "docs": "The **`FileList`** interface represents an object of this type returned by the `files` property of the HTML `input` element; this lets you access the list of files selected with the `` element. It's also used for a list of files dropped into web content when using the drag and drop API; see the [DataTransfer] object for details on this usage.\n\nAll `` element nodes have a `files` attribute of type `FileList` on them which allows access to the items in this list. For example, if the HTML includes the following file input:\n\n```html\n\n```\n\nThe following line of code fetches the first file in the node's file list as a [File] object:\n\n```js\nconst file = document.getElementById(\"fileItem\").files[0];\n```\n\nThis interface was an [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) and only continues to be supported to not break code that's already using it. Modern APIs represent list structures using types based on JavaScript [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), thus making many array methods available, and at the same time imposing additional semantics on their usage (such as making their items read-only).\n\nThese historical reasons do not mean that you as a developer should avoid `FileList`. You don't create `FileList` objects yourself, but you get them from APIs such as [HTMLInputElement.files], and these APIs are not deprecated. However, be careful of the semantic differences from a real array.", "properties": { "item": "The **`item()`** method of the [FileList] interface returns a [File] object representing the file at the specified index in the file list.", "length": "The **`length`** read-only property of the [FileList] interface returns the number of files in the `FileList`." @@ -3087,14 +3091,16 @@ "heading": "The **`heading`** read-only property of the [GeolocationCoordinates] interface is a `double` representing the direction in which the device is traveling. This value, specified in degrees, indicates how far off from heading due north the device is. `0` degrees represents true north, and the direction is determined clockwise (which means that east is `90` degrees and west is `270` degrees). If [GeolocationCoordinates.speed] is `0`, `heading` is `NaN`. If the device is not able to provide heading information, this value is `null`.", "latitude": "The **`latitude`** read-only property of the [GeolocationCoordinates] interface is a `double` representing the latitude of the position in decimal degrees.", "longitude": "The **`longitude`** read-only property of the [GeolocationCoordinates] interface is a number which represents the longitude of a geographical position, specified in decimal degrees.\nTogether with a timestamp, given as in milliseconds, indicating a time of measurement, the `GeolocationCoordinates` object is part of the [GeolocationPosition] interface, which is the object type returned by Geolocation API functions that obtain and return a geographical position.", - "speed": "The **`speed`** read-only property of the [GeolocationCoordinates] interface is a `double` representing the velocity of the device in meters per second. This value is `null` if the implementation is not able to measure it." + "speed": "The **`speed`** read-only property of the [GeolocationCoordinates] interface is a `double` representing the velocity of the device in meters per second. This value is `null` if the implementation is not able to measure it.", + "tojson": "The **`toJSON()`** method of the [GeolocationCoordinates] interface is a ; it returns a JSON representation of the [GeolocationCoordinates] object." } }, "GeolocationPosition": { "docs": "The **`GeolocationPosition`** interface represents the position of the concerned device at a given time. The position, represented by a [GeolocationCoordinates] object, comprehends the 2D position of the device, on a spheroid representing the Earth, but also its altitude and its speed.", "properties": { "coords": "The **`coords`** read-only property of the [GeolocationPosition] interface returns a [GeolocationCoordinates] object representing a geographic position. It contains the location, that is longitude and latitude on the Earth, the altitude, and the speed of the object concerned, regrouped inside the returned value. It also contains accuracy information about these values.", - "timestamp": "The **`timestamp`** read-only property of the [GeolocationPosition] interface represents the date and time that the position was acquired by the device." + "timestamp": "The **`timestamp`** read-only property of the [GeolocationPosition] interface represents the date and time that the position was acquired by the device.", + "tojson": "The **`toJSON()`** method of the [GeolocationPosition] interface is a ; it returns a JSON representation of the [GeolocationPosition] object." } }, "GeolocationPositionError": { @@ -3132,10 +3138,10 @@ } }, "HIDConnectionEvent": { - "docs": "The **`HIDConnectionEvent`** interface of the [WebHID API] represents HID connection events, and is the event type passed to [HID.connect_event] and [HID.disconnect_event] event handlers when an input report is received.", + "docs": "The **`HIDConnectionEvent`** interface of the [WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API) represents HID connection events, and is the event type passed to [HID.connect_event] and [HID.disconnect_event] event handlers when a device's connection state changes.", "properties": { "device": "The **`device`** read-only property of the [HIDConnectionEvent] interface returns the [HIDDevice] associated with this connection event.", - "hidconnectionevent": "The **`HIDConnectionEvent()`** constructor creates a new [HIDConnectionEvent] object. Typically this constructor is not used as events are created when an input report is received." + "hidconnectionevent": "The **`HIDConnectionEvent()`** constructor creates a new [HIDConnectionEvent] object. Typically this constructor is not used as events are created when a device's connection state changes." } }, "HIDDevice": { @@ -3181,6 +3187,7 @@ "HTMLAnchorElement": { "docs": "The **`HTMLAnchorElement`** interface represents hyperlink elements and provides special properties and methods (beyond those of the regular [HTMLElement] object interface that they inherit from) for manipulating the layout and presentation of such elements. This interface corresponds to [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) element; not to be confused with [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link), which is represented by [`HTMLLinkElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLinkElement).", "properties": { + "attributionsrc": "The **`attributionSrc`** property of the [HTMLAnchorElement] interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/a#attributionsrc) attribute on an `a` element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an header. On the server-side this is used to trigger sending an header in the response, to register of a [navigation-based attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#navigation-based_attribution_sources).\n\nThe browser stores the source data associated with the navigation-based attribution source (as provided in the response header) when it receives the navigation response.\n\nSee the [Attribution Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Attribution_Reporting_API) for more details.\n\n> **Note:** `` elements cannot be used as attribution triggers, only sources.", "download": "The **`HTMLAnchorElement.download`** property is a\nstring indicating that the linked resource is intended to be\ndownloaded rather than displayed in the browser. The value, if any, specifies the\ndefault file name for use in labeling the resource in a local file system. If the name\nis not a valid file name in the underlying OS, the browser will adjust it.\n\n> **Note:** This value might not be used for download. This value cannot\n> be used to determine whether the download will occur.", "hash": "The\n**`HTMLAnchorElement.hash`** property returns a\nstring containing a `'#'` followed by the fragment\nidentifier of the URL.\n\nThe fragment is [URL encoded](https://en.wikipedia.org/wiki/URL_encoding). If the URL does not\nhave a fragment identifier, this property contains an empty string, `\"\"`.", "host": "The **`HTMLAnchorElement.host`** property is a\nstring containing the host, that is the _hostname_, and then,\nif the _port_ of the URL is nonempty, a `':'`, and the _port_\nof the URL.", @@ -3261,7 +3268,7 @@ "contextlost_event": "The **`contextlost`** event of the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) is fired if the user agent detects that the backing storage associated with a [`CanvasRenderingContext2D`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) context is lost.\nContexts can be lost for several reasons like driver crashes or the application runs out of memory, etc.\n\nBy default the user agent will attempt to restore the context and then fire the [`contextrestored` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/contextrestored_event).\nUser code can prevent the context from being restored by calling [`Event.preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) during event handling.", "contextrestored_event": "The **`contextrestored`** event of the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) is fired if the user agent restores the backing storage for a [`CanvasRenderingContext2D`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D).\n\nYou can redraw, re-retrieve resources, and reinitialize the state of your context after receiving this event.", "getcontext": "The\n**`HTMLCanvasElement.getContext()`** method returns a drawing\ncontext on the canvas, or [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) if the context identifier is not\nsupported, or the canvas has already been set to a different context mode.\n\nLater calls to this method on the same canvas element, with the same\n`contextType` argument, will always return the same drawing context instance\nas was returned the first time the method was invoked. It is not possible to get a\ndifferent drawing context object on a given canvas element.", - "height": "The **`HTMLCanvasElement.height`** property is a\npositive `integer` reflecting the [`height`](/en-US/docs/Web/HTML/Element/canvas#height) HTML\nattribute of the `canvas` element interpreted in CSS pixels. When the\nattribute is not specified, or if it is set to an invalid value, like a negative, the\ndefault value of `150` is used.\n\nThis is one of the two properties, the other being\n[HTMLCanvasElement.width], that controls the size of the canvas.", + "height": "The **`HTMLCanvasElement.height`** property is a\npositive `integer` reflecting the [`height`](/en-US/docs/Web/HTML/Element/canvas#height) HTML\nattribute of the `canvas` element interpreted in CSS pixels. When the\nattribute is not specified, or if it is set to an invalid value, like a negative, the\ndefault value of `150` is used.\n\nWhen the `height` property is set the drawing buffer is always reset to blank — this is true for all context types, and even when the height is set to the same value. If you need to restore the previous content, you can save it via [CanvasRenderingContext2D.getImageData] and restore it via [CanvasRenderingContext2D.putImageData].\n\nThis is one of the two properties, the other being\n[HTMLCanvasElement.width], that controls the size of the canvas.", "mozopaque": "The non-standard **`HTMLCanvasElement.mozOpaque`** property is\na boolean value reflecting the [`moz-opaque`](/en-US/docs/Web/HTML/Element/canvas#moz-opaque) HTML\nattribute of the `canvas` element. It lets the canvas know whether or\nnot translucency will be a factor. If the canvas knows there's no translucency, painting\nperformance can be optimized.\n\n> **Note:** This has been standardized as setting the `alpha` option to\n> `false` when creating a drawing context with\n> [HTMLCanvasElement.getContext]. Use of `mozOpaque` should be\n> avoided. Firefox will stop supporting it in the future.", "toblob": "The **`HTMLCanvasElement.toBlob()`** method creates a [Blob] object representing the image contained in the canvas.\nThis file may be cached on the disk or stored in memory at the discretion of the user agent.\n\nThe desired file format and image quality may be specified.\nIf the file format is not specified, or if the given format is not supported, then the data will be exported as `image/png`.\nBrowsers are required to support `image/png`; many will support additional formats including `image/jpeg` and `image/webp`.\n\nThe created image will have a resolution of 96dpi for file formats that support encoding resolution metadata.", "todataurl": "The **`HTMLCanvasElement.toDataURL()`** method returns a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) containing a representation of the image in the format specified by the `type` parameter.\n\nThe desired file format and image quality may be specified.\nIf the file format is not specified, or if the given format is not supported, then the data will be exported as `image/png`.\nIn other words, if the returned value starts with `data:image/png` for any other requested `type`, then that format is not supported.\n\nBrowsers are required to support `image/png`; many will support additional formats including `image/jpeg` and `image/webp`.\n\nThe created image data will have a resolution of 96dpi for file formats that support encoding resolution metadata.", @@ -3269,11 +3276,11 @@ "webglcontextcreationerror_event": "The **`webglcontextcreationerror`** event of the [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) is fired if the user agent is unable to create a [WebGLRenderingContext] context.\n\nThis event has a [WebGLContextEvent.statusMessage] property, which can contain a platform dependent string with more information about the failure.\n\nThis event does not bubble.", "webglcontextlost_event": "The **`webglcontextlost`** event of the [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) is fired if the user agent detects that the drawing buffer associated with a [WebGLRenderingContext] object has been lost.\n\nThis event does not bubble.", "webglcontextrestored_event": "The **`webglcontextrestored`** event of the [WebGL API](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) is fired if the user agent restores the drawing buffer for a [WebGLRenderingContext] object.\n\nOnce the context is restored, WebGL resources such as textures and buffers that were created before the context was lost are no longer valid. You need to reinitialize the state of your WebGL application and recreate resources.\n\nThis event does not bubble.", - "width": "The **`HTMLCanvasElement.width`** property is a\npositive `integer` reflecting the [`width`](/en-US/docs/Web/HTML/Element/canvas#width) HTML\nattribute of the `canvas` element interpreted in CSS pixels. When the\nattribute is not specified, or if it is set to an invalid value, like a negative, the\ndefault value of `300` is used.\n\nThis is one of the two properties, the other being\n[HTMLCanvasElement.height], that controls the size of the canvas." + "width": "The **`HTMLCanvasElement.width`** property is a\npositive `integer` reflecting the [`width`](/en-US/docs/Web/HTML/Element/canvas#width) HTML\nattribute of the `canvas` element interpreted in CSS pixels. When the\nattribute is not specified, or if it is set to an invalid value, like a negative, the\ndefault value of `300` is used.\n\nWhen the `width` property is set the drawing buffer is always reset to blank — this is true for all context types, and even when the width is set to the same value. If you need to restore the previous content, you can save it via [CanvasRenderingContext2D.getImageData] and restore it via [CanvasRenderingContext2D.putImageData].\n\nThis is one of the two properties, the other being\n[HTMLCanvasElement.height], that controls the size of the canvas." } }, "HTMLCollection": { - "docs": "The **`HTMLCollection`** interface represents a generic collection (array-like object similar to `arguments`) of elements (in document order) and offers methods and properties for selecting from the list.\n\n> **Note:** This interface is called `HTMLCollection` for historical reasons (before the modern DOM, collections implementing this interface could only have HTML elements as their items).\n\nAn `HTMLCollection` in the HTML DOM is live; it is automatically updated when the underlying document is changed. For this reason it is a good idea to make a copy (e.g., using `Array.from`) to iterate over if adding, moving, or removing nodes.\n\n> **Note:** This interface was an [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) and only continues to be supported to not break code that's already using it. Modern APIs use types that wrap around ECMAScript array types instead, so you can treat them like ECMAScript arrays, and at the same time impose additional semantics on their usage (such as making their items read-only).", + "docs": "The **`HTMLCollection`** interface represents a generic collection (array-like object similar to `arguments`) of elements (in document order) and offers methods and properties for selecting from the list.\n\nAn `HTMLCollection` in the HTML DOM is live; it is automatically updated when the underlying document is changed. For this reason it is a good idea to make a copy (e.g., using `Array.from`) to iterate over if adding, moving, or removing nodes.\n\nThis interface is called `HTMLCollection` for historical reasons, because before the modern DOM, collections implementing this interface could only have HTML elements as their items.\n\nThis interface was an [attempt to create an unmodifiable list](https://stackoverflow.com/questions/74630989/why-use-domstringlist-rather-than-an-array/74641156#74641156) and only continues to be supported to not break code that's already using it. Modern APIs represent list structures using types based on JavaScript [arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), thus making many array methods available, and at the same time imposing additional semantics on their usage (such as making their items read-only).\n\nThese historical reasons do not mean that you as a developer should avoid `HTMLCollection`. You don't create `HTMLCollection` objects yourself, but you get them from APIs such as [Document.getElementsByClassName], and these APIs are not deprecated. However, be careful of the semantic differences from a real array.", "properties": { "item": "The [HTMLCollection] method `item()`\nreturns the element located at the specified offset into the collection.\n\n> **Note:** Because the contents of an `HTMLCollection` are\n> live, changes to the underlying DOM can and will cause the position of individual\n> elements in the collection to change, so the index value will not necessarily remain\n> constant for a given element.", "length": "The **`HTMLCollection.length`** property returns the number of\nitems in a [HTMLCollection].", @@ -3321,10 +3328,11 @@ "properties": { "accesskey": "The **`HTMLElement.accessKey`** property sets the keystroke which a user can press to jump to a given element.\n\n> **Note:** The `HTMLElement.accessKey` property is seldom used because of its multiple conflicts with already present key bindings in browsers. To work around this, browsers implement accesskey behavior if the keys are pressed with other \"qualifying\" keys (such as Alt + accesskey).", "accesskeylabel": "The **`HTMLElement.accessKeyLabel`**\nread-only property returns a string containing the element's\nbrowser-assigned access key (if any); otherwise it returns an empty string.", + "anchorelement": "The **`anchorElement`** property of the [HTMLElement] interface returns a reference to the element's anchor element. This works only in the case of elements associated with their anchors via the [`anchor`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/anchor) HTML attribute, not elements associated with their anchors via the CSS and properties.\n\nFor detailed information on anchor features and usage, see the [CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning) module landing page and the [Using CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning/Using) guide.", "attachinternals": "The **`HTMLElement.attachInternals()`** method returns an [ElementInternals] object.\nThis method allows a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) to participate in HTML forms. The `ElementInternals` interface provides utilities for working with these elements in the same way you would work with any standard HTML form element, and also exposes the [Accessibility Object Model](https://wicg.github.io/aom/explainer.html) to the element.", - "attributestylemap": "The **`attributeStyleMap`** read-only property of the [HTMLElement] interface returns a live [StylePropertyMap] object that contains a list of style properties of the element that are defined in the element's inline [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/style) attribute, or assigned using the [HTMLElement.style] property of the [HTMLElement] interface via script.\n\nShorthand properties are expanded. If you set `border-top: 1px solid black`, the longhand properties (, , and ) are set instead.\n\nThe main difference between [HTMLElement.style] property and `attributeStyleMap` property is that, the `style` property will return a [CSSStyleDeclaration] object, while the `attributeStyleMap` property will return a [StylePropertyMap] object.\n\nThough the property itself is not writable, you could read and write inline styles through the [StylePropertyMap] object that it returns, just like through the [CSSStyleDeclaration] object that returns via the `style` property.", + "attributestylemap": "The **`attributeStyleMap`** read-only property of the [HTMLElement] interface returns a live [StylePropertyMap] object that contains a list of style properties of the element that are defined in the element's inline `style` attribute, or assigned using the [HTMLElement.style] property of the [HTMLElement] interface via script.\n\nShorthand properties are expanded. If you set `border-top: 1px solid black`, the longhand properties (, , and ) are set instead.\n\nThe main difference between [HTMLElement.style] property and `attributeStyleMap` property is that, the `style` property will return a [CSSStyleDeclaration] object, while the `attributeStyleMap` property will return a [StylePropertyMap] object.\n\nThough the property itself is not writable, you could read and write inline styles through the [StylePropertyMap] object that it returns, just like through the [CSSStyleDeclaration] object that returns via the `style` property.", "autocapitalize": "The **`autocapitalize`** property of the [HTMLElement] interface represents the element's capitalization behavior for user input. It is available on all HTML elements, though it doesn't affect all of them, including:\n\n- `input` and `textarea` elements.\n- Any element with [`contenteditable`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable) set on it.\n\n`autocapitalize` doesn't affect behavior when typing on a physical keyboard. It affects the behavior of other input mechanisms such as virtual keyboards on mobile devices and voice input. This can assist users by making data entry quicker and easier, for example by automatically capitalizing the first letter of each sentence.\n\nIt reflects the value of the [`autocapitalize`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autocapitalize) HTML global attribute.", - "autofocus": "The **`autofocus`** property of the [HTMLElement] interface represents a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Element/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside `dialog` elements or elements whose popover attribute is set.\n\nOnly one form-associated element inside a document, or a `dialog` element, or an element whose `popover` attribute is set, can have this attribute specified. If there are several, the first element with the attribute set inserted, usually the first such element on the page, get the initial focus.\n\n> **Note:** Setting this property doesn't set the focus to the associated element: it merely tells the browser to focus to it when _the element is inserted_ in the document. Setting it after the insertion, that is most of the time after the document load, has no visible effect.", + "autofocus": "The **`autofocus`** property of the [HTMLElement] interface represents a boolean value reflecting the [`autofocus`](/en-US/docs/Web/HTML/Element/select#autofocus) HTML global attribute, which indicates whether the control should be focused when the page loads, or when dialog or popover become shown if specified in an element inside `dialog` elements or elements whose popover attribute is set.\n\nOnly one form-associated element inside a document, or a `dialog` element, or an element whose `popover` attribute is set, can have this attribute specified. If there are several, the first element with the attribute set inserted, usually the first such element on the page, gets the initial focus.\n\n> **Note:** Setting this property doesn't set the focus to the associated element: it merely tells the browser to focus to it when _the element is inserted_ in the document. Setting it after the insertion, that is most of the time after the document load, has no visible effect.", "beforetoggle_event": "The **`beforetoggle`** event of the [HTMLElement] interface fires on a [Popover_API] element (i.e. one that has a valid [`popover`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover) attribute) just before it is shown or hidden.\n\n- If the popover is transitioning from hidden to showing, the `event.oldState` property will be set to `closed` and the `event.newState` property will be set to `open`.\n- If the popover is transitioning from showing to hidden, then `event.oldState` will be `open` and `event.newState` will be `closed`.", "blur": "The **`HTMLElement.blur()`** method removes keyboard focus from the current element.", "cancel_event": "The **`cancel`** event is fired by `input` and `dialog` elements. The event is fired when the user cancels the currently open dialog by closing it with the Esc key. It is also fired by the [file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) when the user cancels the file picker dialog via the Esc key or the cancel button and when the user re-selects the same files that were previously selected.\n\nThis event does not bubble.\n\nWhen a `` is dismissed with the Esc key, both the `cancel` and [HTMLDialogElement.close_event] events are fired.", @@ -3333,7 +3341,7 @@ "contenteditable": "The **`contentEditable`** property of\nthe [HTMLElement] interface specifies whether or not the element is\neditable.\n\nThis enumerated attribute can have the following values:\n\n- '`true`' indicates that the element is `contenteditable`.\n- '`false`' indicates that the element cannot be edited.\n- '`plaintext-only`' indicates that the element's raw text is editable, but rich text formatting is disabled.\n\nYou can use the [HTMLElement.isContentEditable] property to test the\ncomputed boolean value of this property.\n\nIf the attribute is missing or its value is invalid, its value is inherited from its parent element: so the element\nis editable (or not) based on the parent element.", "copy_event": "The **`copy`** event fires when the user initiates a copy action through the browser's user interface.", "cut_event": "The **`cut`** event fires when the user initiates a cut action through the browser's user interface.", - "dataset": "The **`dataset`** read-only property\nof the [HTMLElement] interface provides read/write access to [custom data attributes](/en-US/docs/Web/HTML/Global_attributes/data-*)\n(`data-*`) on elements. It exposes a map of strings\n([DOMStringMap]) with an entry for each `data-*` attribute.\n\n> **Note:** The `dataset` property itself can be read, but not directly written.\n> Instead, all writes must be to the individual properties within the\n> `dataset`, which in turn represent the data attributes.\n\nAn HTML `data-*` attribute and its corresponding DOM\n`dataset.property` modify their shared name according to where\nthey are read or written:\n\n- In HTML\n - : The attribute name begins with `data-`. It can contain only letters,\n numbers, dashes (`-`), periods (`.`), colons (`:`),\n and underscores (`_`). Any capital letters (`A` to\n `Z`) are converted to lowercase.\n- In JavaScript\n - : The property name of a custom data attribute is the same as the HTML attribute\n without the `data-` prefix, and removes single dashes (`-`) for\n when to capitalize the property's \"\" name.\n\nIn addition to the information below, you'll find a how-to guide for using HTML data\nattributes in our article [_Using data attributes_](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).\n\n### Name conversion\n\n- `dash-style` to `camelCase` conversion\n\n - : A custom data attribute name is transformed to a key for the\n [DOMStringMap] entry by the following:\n\n 1. Lowercase all ASCII capital letters (`A` to\n `Z`);\n 2. Remove the prefix `data-` (including the dash);\n 3. For any dash (`U+002D`) followed by an ASCII lowercase letter\n `a` to `z`, remove the dash and uppercase the letter;\n 4. Other characters (including other dashes) are left unchanged.\n\n- `camelCase` to `dash-style` conversion\n\n - : The opposite transformation, which maps a key to an attribute name, uses the\n following:\n\n 1. **Restriction:** Before transformation, a dash _must not_ be\n immediately followed by an ASCII lowercase letter `a` to\n `z`;\n 2. Add the `data-` prefix;\n 3. Add a dash before any ASCII uppercase letter `A` to `Z`,\n then lowercase the letter;\n 4. Other characters are left unchanged.\n\nFor example, a `data-abc-def` attribute corresponds to\n`dataset.abcDef`.\n\n### Accessing values\n\n- Attributes can be set and read by the camelCase name/key as an object property of\n the dataset: `element.dataset.keyname`.\n- Attributes can also be set and read using bracket syntax:\n `element.dataset['keyname']`.\n- The [`in` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in) can check if a given attribute exists:\n `'keyname' in element.dataset`.\n\n### Setting values\n\n- When the attribute is set, its value is always converted to a string.\n For example: `element.dataset.example = null` is\n converted into `data-example=\"null\"`.\n\n- To remove an attribute, you can use the [`delete` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete): `delete element.dataset.keyname`.", + "dataset": "The **`dataset`** read-only property\nof the [HTMLElement] interface provides read/write access to [custom data attributes](/en-US/docs/Web/HTML/Global_attributes/data-*)\n(`data-*`) on elements. It exposes a map of strings\n([DOMStringMap]) with an entry for each `data-*` attribute.\n\n> **Note:** The `dataset` property itself can be read, but not directly written.\n> Instead, all writes must be to the individual properties within the\n> `dataset`, which in turn represent the data attributes.\n\nAn HTML `data-*` attribute and its corresponding DOM\n`dataset.property` modify their shared name according to where\nthey are read or written:\n\n- In HTML\n - : The attribute name begins with `data-`. It can contain only letters,\n numbers, dashes (`-`), periods (`.`), colons (`:`),\n and underscores (`_`). Any capital letters (`A` to\n `Z`) are converted to lowercase.\n- In JavaScript\n - : The property name of a custom data attribute is the same as the HTML attribute\n without the `data-` prefix, and removes single dashes (`-`) for\n when to capitalize the property's \"\" name.\n\nIn addition to the information below, you'll find a how-to guide for using HTML data\nattributes in our article [_Using data attributes_](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).\n\n### Name conversion\n\n- `dash-style` to `camelCase` conversion\n\n - : A custom data attribute name is transformed to a key for the\n [DOMStringMap] entry by the following:\n\n 1. Lowercase all ASCII capital letters (`A` to\n `Z`);\n 2. Remove the prefix `data-` (including the dash);\n 3. For any dash (`U+002D`) followed by an ASCII lowercase letter\n `a` to `z`, remove the dash and uppercase the letter;\n 4. Other characters (including other dashes) are left unchanged.\n\n- `camelCase` to `dash-style` conversion\n\n - : The opposite transformation, which maps a key to an attribute name, uses the\n following:\n\n 1. **Restriction:** Before transformation, a dash _must not_ be\n immediately followed by an ASCII lowercase letter `a` to\n `z`;\n 2. Add the `data-` prefix;\n 3. Add a dash before any ASCII uppercase letter `A` to `Z`,\n then lowercase the letter;\n 4. Other characters are left unchanged.\n\nFor example, a `data-abc-def` attribute corresponds to\n`dataset.abcDef`.\n\n### Accessing values\n\n- Attributes can be set and read by the camelCase name/key as an object property of\n the dataset: `element.dataset.keyname`.\n- Attributes can also be set and read using bracket syntax:\n `element.dataset['keyname']`.\n- The [`in` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/in) can check if a given attribute exists:\n `'keyname' in element.dataset`. Note that this will walk the [prototype chain](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) of `dataset` and may be unsafe if you have external code that may pollute the prototype chain. Several alternatives exist, such as `'keyname')\"`, or just checking if `element.dataset.keyname !== undefined`.\n\n### Setting values\n\n- When the attribute is set, its value is always converted to a string.\n For example: `element.dataset.example = null` is\n converted into `data-example=\"null\"`.\n\n- To remove an attribute, you can use the [`delete` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/delete): `delete element.dataset.keyname`.", "dir": "The **`HTMLElement.dir`** property gets or sets the text\nwriting directionality of the content of the current element.\n\nThe text writing directionality of an element is which direction that text goes (for\nsupport of different language systems). Arabic languages and Hebrew are typical\nlanguages using the RTL directionality.\n\nAn image can have its `dir` property set to \"`rtl`\" in which case\nthe HTML attributes `title` and `alt` will be formatted and\ndefined as \"`rtl`\".\n\nWhen a table has its `dir` set to \"`rtl`\", the column order is\narranged from right to left.\n\nWhen an element has its dir set to \"`auto`\", the direction of the element is\ndetermined based on its first strong directionality character, or default to the\ndirectionality of its parent element.\n\n> **Note:** Browsers might allow users to change the directionality of `input`\n> and `textarea`s in order to assist with authoring content. Chrome\n> and Safari provide a directionality option in the contextual menu of input fields\n> while pre-Chromium Edge uses the key combinations Ctrl + Left Shift and Ctrl + Right Shift. Firefox uses Ctrl/Cmd + Shift + X but does NOT update\n> the **`dir`** attribute value.", "drag_event": "The `drag` event is fired every few hundred milliseconds as an element or text selection is being dragged by the user.\n\nThis event is cancelable and may bubble up to the [Document] and [Window] objects.", "dragend_event": "The `dragend` event is fired when a drag operation ends (by releasing a mouse button or hitting the escape key).\n\nThis event is cancelable and may bubble up to the [Document] and [Window] objects.", @@ -3475,6 +3483,7 @@ "properties": { "align": "The _obsolete_ **`align`**\nproperty of the [HTMLImageElement] interface is a string which indicates\nhow to position the image relative to its container.\n\nYou should instead use the\nCSS property , which does in fact also work on images\ndespite its name. You can also use the `float` property to float the image\nto the left or right margin.\n\nThe `align` property reflects the HTML [`align`](/en-US/docs/Web/HTML/Element/img#align)\ncontent attribute.", "alt": "The [HTMLImageElement] property **`alt`** provides fallback (alternate) text to display when the image specified by the `img` element is not loaded.\n\nThis may be the case because of an error, because the user has disabled the loading of images, or because the image hasn't finished loading yet.\n\nPerhaps the most important reason to use the `alt` property is to support [accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility), as the `alt` text may be used by screen readers and other assistive technologies to help people with a disability make full use of your content.\nIt will be read aloud or sent to a braille output device, for example, to support blind or visually impaired users.\n\n> **Think of it like this:** When choosing `alt` strings for your images, imagine what you would say when reading the page to someone over the phone without mentioning that there's an image on the page.\n\nThe alternate text is displayed in the space the image would occupy and should be able to take the place of the image _without altering the meaning of the page_.", + "attributionsrc": "The\n**`attributionSrc`** property of the [HTMLImageElement] interface gets and sets the [`attributionsrc`](/en-US/docs/Web/HTML/Element/img#attributionsrc) attribute on an `img` element programmatically, reflecting the value of that attribute. `attributionsrc` specifies that you want the browser to send an header along with the image request.\n\nOn the server-side this is used to trigger sending an or header in the response, to register an image-based [attribution source](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_sources#html-based_event_sources) or [attribution trigger](/en-US/docs/Web/API/Attribution_Reporting_API/Registering_triggers#html-based_attribution_triggers), respectively. Which response header should be sent back depends on the value of the `Attribution-Reporting-Eligible` header that triggered the registration.\n\nThe source/trigger is registered once the browser receives the response containing the image file.\n\n> **Note:** Bear in mind that users might not necessarily be able to perceive the image at all — it might be a 1x1 transparent tracking pixel that is only being used for attribution reporting.\n\nSee the [Attribution Reporting API](https://developer.mozilla.org/en-US/docs/Web/API/Attribution_Reporting_API) for more details.", "border": "The obsolete [HTMLImageElement]\nproperty **`border`** specifies the number of pixels thick the\nborder surrounding the image should be. A value of 0, the default, indicates that no\nborder should be drawn.\n\nYou should _not_ use this property! Instead, you should use CSS to style the\nborder. The `border` property or its longhand properties to not only set\nthe thickness of the border but to potentially apply a wide variety of other styling\noptions to it.\n\nThe width, specifically, is controlled using the writing-mode aware\n, ,\n, and \nproperties.\n\nFor compatibility (or perhaps other) reasons, you can use the older properties instead\n(or in addition): , ,\n, and .", "complete": "The read-only [HTMLImageElement] interface's\n**`complete`** attribute is a Boolean value which indicates\nwhether or not the image has completely loaded.", "crossorigin": "The [HTMLImageElement]\ninterface's **`crossOrigin`** attribute is a string which\nspecifies the Cross-Origin Resource Sharing () setting to use when\nretrieving the image.", @@ -3523,7 +3532,7 @@ "selectionstart": "The **`selectionStart`** property of the [HTMLInputElement] interface is a number that represents the beginning index of the selected text. When nothing is selected, then returns the position of the text input cursor (caret) inside of the `` element.\n\n> **Note:** According to the [WHATWG forms spec](https://html.spec.whatwg.org/multipage/forms.html#concept-input-apply) `selectionStart` property applies only to inputs of types text, search, URL, tel, and password. In modern browsers, throws an exception while setting `selectionStart` property on the rest of input types. Additionally, this property returns `null` while accessing `selectionStart` property on non-text input elements.\n\nIf `selectionStart` is greater than `selectionEnd`, then both are\ntreated as the value of `selectionEnd`.", "setcustomvalidity": "The **`HTMLInputElement.setCustomValidity()`** method sets a custom validity message for the element.", "setrangetext": "The **`HTMLInputElement.setRangeText()`** method replaces a\nrange of text in an `input` or `textarea` element with\na new string.", - "setselectionrange": "The **`HTMLInputElement.setSelectionRange()`** method sets the\nstart and end positions of the current text selection in an `input`\nor `textarea` element.\n\nOptionally, in newer browser versions, you can specify the direction in which selection\nshould be considered to have occurred. This lets you indicate, for example, that the\nselection was set by the user clicking and dragging from the end of the selected text\ntoward the beginning.\n\nThis method updates the `HTMLInputElement.selectionStart`,\n`selectionEnd`, and `selectionDirection` properties in one call.\n\nNote that according to the [WHATWG forms spec](https://html.spec.whatwg.org/multipage/forms.html#concept-input-apply) `selectionStart`, `selectionEnd` properties and\n`setSelectionRange` method apply only to inputs of types text, search, URL,\ntel and password. Chrome, starting from version 33, throws an exception while accessing\nthose properties and method on the rest of input types. For example, on input of type\nnumber: \"Failed to read the 'selectionStart' property from 'HTMLInputElement': The input\nelement's type ('number') does not support selection\".\n\nIf you wish to select **all** text of an input element, you can use the [HTMLInputElement.select()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select)\nmethod instead.", + "setselectionrange": "The **`HTMLInputElement.setSelectionRange()`** method sets the start and end positions of the current text selection in an `input` or `textarea` element.\n\nThe element must be focused for the call to have any effect.\n\nOptionally, you can specify the direction in which selection should be considered to have occurred. This lets you indicate, for example, that the selection was set by the user clicking and dragging from the end of the selected text toward the beginning.\n\nThis method updates the [HTMLInputElement.selectionStart], [HTMLInputElement.selectionEnd], and [HTMLInputElement.selectionDirection] properties in one call.\n\nThe element must be of one of the following input types: [`password`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password), [`search`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search), [`tel`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/tel), [`text`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text), or [`url`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/url). Otherwise the browser throws an `InvalidStateError` exception.\n\nIf you wish to select **all** text of an input element, you can use the [HTMLInputElement.select()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/select) method instead.", "showpicker": "The **`HTMLInputElement.showPicker()`** method displays the browser picker for an `input` element.\n\nThis is the same picker that would normally be displayed when the element is selected, but can be triggered from a button press or other user interaction.\n\nCommonly browsers implement it for inputs of these types: `\"date\"`, `\"month\"`, `\"week\"`, `\"time\"`, `\"datetime-local\"`, `\"color\"`, or `\"file\"`.\nIt can also be prepopulated with items from a `datalist` element or [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) attribute.\n\nMore generally, this method should ideally display the picker for any input element on the platform that has a picker.", "stepdown": "The\n**`HTMLInputElement.stepDown([n])`** method decrements the\nvalue of a numeric type of `input` element by the value of the\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) attribute or up\nto `n` multiples of the step attribute if a number is passed as the\nparameter.\n\nThe method, when invoked, decrements the\n[`value`](/en-US/docs/Web/HTML/Element/input#value) by ([`step`](/en-US/docs/Web/HTML/Element/input#step) \\* n), where n\ndefaults to 1 if not specified, and\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) defaults to the\ndefault value for `step` if not specified.\n\nValid on all numeric, date, and time input types that support the step attribute,\nincluding `date`, `month`,\n`week`, `time`,\n,\n`number`, and `range`.\n\nGiven ``,\ninvoking `myTime.stepDown(3)` will change the value to 16:15, decrementing the\ntime by `3 * 900`, or 45 minutes. `myTime.stepDown()`, with no\nparameter, would have resulted in `16:45`, as `n` defaults to\n`1`.\n\n```html\n\n\n\n\n\n\n\n\n```\n\nHowever, calling `stepDown` on `` would not set the value to `17:00`, as one would expect — and as it does for `stepUp` when the input is ``. Instead, the first call to `stepDown` will set the initial value to `23:45` even though the `max` attribute is set. The second call will set the value to `17:00`. And the third call to will set the value to `16:45`.\n\n```js\nlet input1 = document.createElement(\"input\");\ninput1.setAttribute(\"type\", \"time\");\ninput1.setAttribute(\"min\", \"17:00\");\ninput1.setAttribute(\"step\", 900);\nconsole.log(input1.value); // \"\"\ninput1.stepUp();\nconsole.log(input1.value); // \"17:00\"\n// However\nlet input2 = document.createElement(\"input\");\ninput2.setAttribute(\"type\", \"time\");\ninput2.setAttribute(\"max\", \"17:00\");\ninput2.setAttribute(\"step\", 900);\nconsole.log(input2.value); // \"\"\ninput2.stepDown();\nconsole.log(input2.value); // \"23:45\"\ninput2.stepDown();\nconsole.log(input2.value); // \"17:00\"\ninput2.stepDown();\nconsole.log(input2.value); // \"16:45\"\n```\n\nThe method, when invoked, changes the form control's value by the value given in the\n`step` attribute, multiplied by the parameter, within the constraints set\nwithin the form control. The default value for the parameter, if not is passed, is 1.\nThe method will not cause the value to go below the\n[`min`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min) value set or defy the\nconstraints set by the\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) attribute. A\nnegative value for `n` will increment the value, but will not increment\nbeyond the [`max`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max) value.\n\nIf the value before invoking the `stepDown()` method is invalid, for\nexample, if it doesn't match the constraints set by the `step` attribute,\ninvoking the `stepDown()` method will return a value that does match the form\ncontrols constraints.\n\nIf the form control is non time, date, or numeric in nature, and therefore does not\nsupport the `step` attribute (see the list of supported input types above), or if the `step` value is set to `any`, an\n`InvalidStateError` exception is thrown.\n\n- [HTMLInputElement.stepDown]\n\n - : Decrements the [`value`](/en-US/docs/Web/HTML/Element/input#value) by\n ([`step`](/en-US/docs/Web/HTML/Element/input#step) \\* n), where n defaults to 1 if not specified. Throws\n an `InvalidStateError` exception:\n\n - if the method is not applicable to for the current\n [`type`](/en-US/docs/Web/HTML/Element/input#type) value,\n - if the element has no [`step`](/en-US/docs/Web/HTML/Element/input#step) value,\n - if the [`value`](/en-US/docs/Web/HTML/Element/input#value) cannot be converted to a number,\n - if the resulting value is above the [`max`](/en-US/docs/Web/HTML/Element/input#max) or below the\n [`min`](/en-US/docs/Web/HTML/Element/input#min).", "stepup": "The **`HTMLInputElement.stepUp()`** method increments the value\nof a numeric type of `input` element by the value of the\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) attribute, or the\ndefault `step` value if the step attribute is not explicitly set. The method,\nwhen invoked, increments the [`value`](/en-US/docs/Web/HTML/Element/input#value) by\n([`step`](/en-US/docs/Web/HTML/Element/input#step) \\* n), where `n` defaults to\n`1` if not specified, and\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) defaults to the\ndefault value for `step` if not specified.\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Input typeDefault step valueExample step declaration
`date`1 (day)\n 7 day (one week) increments:
\n <input type=\"date\" min=\"2019-12-25\" step=\"7\">\n
`month`1 (month)\n 12 month (one year) increments:
\n <input type=\"month\" min=\"2019-12\" step=\"12\">\n
`week`1 (week)\n Two week increments:
\n <input type=\"week\" min=\"2019-W23\" step=\"2\">\n
`time`60 (seconds)\n 900 second (15 minute) increments:
\n <input type=\"time\" min=\"09:00\" step=\"900\">\n
\n \n 1 (day)\n Same day of the week:
\n <input type=\"datetime-local\" min=\"019-12-25T19:30\"\n step=\"7\">\n
`number`1\n 0.1 increments
\n <input type=\"number\" min=\"0\" step=\"0.1\" max=\"10\">\n
`range`1\n Increments by 2:
\n <input type=\"range\" min=\"0\" step=\"2\" max=\"10\">\n
\n\nThe method, when invoked, changes the form control's value by the value given in the\n`step` attribute, multiplied by the parameter, within the constraints set on\nthe form control. The default value for the parameter, if no value is passed, is\n`1`. The method will not cause the value to exceed the\nset [`max`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max) value, or defy\nthe constraints set by the\n[`step`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/step) attribute.\n\nIf the value before invoking the `stepUp()` method is invalid—for example,\nif it doesn't match the constraints set by the step attribute—invoking the\n`stepUp()` method will return a value that does match the form controls\nconstraints.\n\nIf the form control is non time, date, or numeric in nature, and therefore does not\nsupport the `step` attribute (see the list of supported input types in the\ntable above), or if the step value is set to `any`, an\n`InvalidStateError` exception is thrown.", @@ -3595,7 +3604,7 @@ "duration": "The _read-only_ [HTMLMediaElement]\nproperty **`duration`** indicates the length of the element's\nmedia in seconds.", "durationchange_event": "The `durationchange` event is fired when the `duration` attribute has been updated.", "emptied_event": "The `emptied` event is fired when the media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the `load()` method is called to reload it.\n\nThis event is not cancelable and does not bubble.", - "encrypted_event": "The `encrypted` event is fired when the media encounters some initialization data indicating it is encrypted.\n\nThis event is not cancelable and does not bubble.", + "encrypted_event": "The `encrypted` event is fired when initialization data is found in the media, indicating that it is encrypted.\n\nThis event is not cancelable and does not bubble.", "ended": "The **`HTMLMediaElement.ended`** property indicates whether the media\nelement has ended playback.", "ended_event": "The `ended` event is fired when playback or streaming has stopped because the end of the media was reached or because no further data is available.\n\nThis event occurs based upon [HTMLMediaElement] (`audio` and `video`) fire `ended` when playback reaches the end of the media.\n\nThis event is not cancelable and does not bubble.", "error": "The **`HTMLMediaElement.error`** property is the\n[MediaError] object for the most recent error, or `null` if\nthere has not been an error. When an [HTMLMediaElement.error_event] event is received by the\nelement, you can determine details about what happened by examining this object.", @@ -3627,7 +3636,7 @@ "seeked_event": "The `seeked` event is fired when a seek operation completed, the current playback position has changed, and the Boolean `seeking` attribute is changed to `false`.\n\nThis event is not cancelable and does not bubble.", "seeking_event": "The `seeking` event is fired when a seek operation starts, meaning the Boolean `seeking` attribute has changed to `true` and the media is seeking a new position.\n\nThis event is not cancelable and does not bubble.", "seektonextframe": "The **`HTMLMediaElement.seekToNextFrame()`** method\nasynchronously advances the current play position to the next frame in the media.\n\n> **Warning:** This non-standard method is part of an experimentation process around support for\n> non-real-time access to media for tasks including filtering, editing, and so forth.\n> You should _not_ use this method in production code, because its implementation\n> may change—or be removed outright—without notice. You are, however, invited to\n> experiment with it.\n\nThis method lets you access frames of video media without the media being performed in\nreal time. This also lets you access media using frames as a seek unit rather than\ntimecodes (albeit only by seeking one frame at a time until you get to the frame you\nwant). Possible uses for this method include filtering and editing of video content.\n\nThis method returns immediately, returning a `Promise`, whose fulfillment\nhandler is called when the seek operation is complete. In addition, a\n[HTMLMediaElement.seeked_event] event is sent to let interested parties know that a seek has taken\nplace. If the seek fails because the media is already at the last frame, a\n[HTMLMediaElement.seeked_event] event occurs, followed immediately by an [HTMLMediaElement.ended_event] event.\n\nIf there is no video on the media element, or the media isn't seekable, nothing\nhappens.", - "setmediakeys": "The **`setMediaKeys()`** method of the\n[HTMLMediaElement] interface returns a `Promise` that resolves\nto the passed [MediaKeys], which are those used to decrypt media during\nplayback.", + "setmediakeys": "The **`setMediaKeys()`** method of the [HTMLMediaElement] interface sets the [MediaKeys] that will be used to decrypt media during playback.\n\nIt returns a `Promise` that fulfils if the new keys are successfully set, or rejects if keys cannot be set.", "setsinkid": "The **`HTMLMediaElement.setSinkId()`** method of the [Audio Output Devices API](https://developer.mozilla.org/en-US/docs/Web/API/Audio_Output_Devices_API) sets the ID of the audio device to use for output and returns a `Promise`.\n\nThis only works when the application is permitted to use the specified device.\nFor more information see the [security requirements](#security_requirements) below.", "sinkid": "The **`HTMLMediaElement.sinkId`** read-only property of the [Audio Output Devices API](https://developer.mozilla.org/en-US/docs/Web/API/Audio_Output_Devices_API) returns a string that is the unique ID of the device to be used for playing audio output.\n\nThis ID should be one of the [MediaDeviceInfo.deviceId] values returned from [MediaDevices.enumerateDevices], `id-multimedia`, or `id-communications`.\nIf the user agent default device is being used, it returns an empty string.", "src": "The **`HTMLMediaElement.src`** property reflects the value of\nthe HTML media element's `src` attribute, which indicates the URL of a media\nresource to use in the element.\n\n> **Note:** The best way to know the URL of the media resource currently\n> in active use in this element is to look at the value of the\n> [HTMLMediaElement.currentSrc] attribute, which also takes\n> into account selection of a best or preferred media resource from a list provided in\n> an [HTMLSourceElement] (which represents a `source`\n> element).", @@ -3740,6 +3749,7 @@ "docs": "HTML `script` elements expose the **`HTMLScriptElement`** interface, which provides special properties and methods for manipulating the behavior and execution of `