draft Invokers API docs

files/en-us/web/api/htmlbuttonelement/invokeaction/index.md

@@ -0,0 +1,38 @@
+---
+title: "HTMLButtonElement: invokeAction property"
+short-title: invokeAction
+slug: Web/API/HTMLButtonElement/invokeAction
+page-type: web-api-instance-property
+browser-compat: api.HTMLButtonElement.invokeAction
+---
+
+{{ APIRef("DOM") }}
+
+The **`invokeAction`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the action to be performed on an element being controlled by a button. For this to have an effect, [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget) must be set.
+
+It reflects the [`invokeaction`](/en-US/docs/Web/HTML/Element/button#invokeaction) HTML attribute.
+
+## Value
+
+A string.
+
+## Examples
+
+```js
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+toggleBtn.invokeAction = "showPopover";
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)

files/en-us/web/api/htmlbuttonelement/invoketargetelement/index.md

@@ -0,0 +1,38 @@
+---
+title: "HTMLButtonElement: invokeTargetElement property"
+short-title: invokeTargetElement
+slug: Web/API/HTMLButtonElement/invokeTargetElement
+page-type: web-api-instance-property
+browser-compat: api.HTMLButtonElement.invokeTargetElement
+---
+
+{{ APIRef("DOM") }}
+
+The **`invokeTargetElement`** property of the {{domxref("HTMLButtonElement")}} interface gets and sets the element to control via a button.
+
+It is the JavaScript equivalent of the [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget) HTML attribute.
+
+## Value
+
+A reference to an element in the DOM.
+
+## Examples
+
+```js
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+toggleBtn.invokeTargetElement = popover;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)

files/en-us/web/api/htmlelement/invoke_event/index.md

@@ -0,0 +1,75 @@
+---
+title: "HTMLElement: invoke event"
+slug: Web/API/HTMLElement/invoke_event
+page-type: web-api-event
+status:
+  - experimental
+browser-compat: api.HTMLElement.invoke_event
+---
+
+{{APIRef}}{{SeeCompatTable}}
+
+The **`invoke`** event of the {{domxref("HTMLElement")}} interface fires on a {{domxref("Invokers_API", "invoker controlled", "", "nocode")}} element (i.e. one that has a button with an `invoketarget` attribute pointing to this element) whenever the invoker is interacted with (e.g. it is clicked).
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener("invoke", (event) => {});
+
+oninvoke = (event) => {};
+```
+
+## Event type
+
+A {{domxref("InvokeEvent")}}. Inherits from {{domxref("Event")}}.
+
+{{InheritanceDiagram("InvokeEvent")}}
+
+## Examples
+
+### Basic example
+
+```js
+const popover = document.getElementById("mypopover");
+
+// ...
+
+popover.addEventListener("invoke", (event) => {
+  if (event.action === "show") {
+    console.log("Popover is about to be shown");
+  }
+});
+```
+
+### A note on event dispatch and cancellation
+
+It is worth pointing out that `invoke` events fire on the element being invoked. If an Invoker (i.e. the `<button>`) is clicked, it will first dispatch a `click` event which, if cancelled, then the `invoke` event will not fire and the default behavior will not be run.
+In addition to cancelling the `click` event on the button, it is also possible to cancel the `invoke` event.
+
+For example:
+
+```js
+button.addEventListener("click", (event) => {
+  event.preventDefault(); // the `invoke` event will never fire
+});
+```
+
+```js
+element.addEventListener("invoke", (event) => {
+  event.preventDefault(); // the `invoke` event fires but the default behavior is cancelled
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)

files/en-us/web/api/htmlinputelement/invokeaction/index.md

@@ -0,0 +1,38 @@
+---
+title: "HTMLInputElement: invokeAction property"
+short-title: invokeAction
+slug: Web/API/HTMLInputElement/invokeAction
+page-type: web-api-instance-property
+browser-compat: api.HTMLInputElement.invokeAction
+---
+
+{{ APIRef("DOM") }}
+
+The **`invokeAction`** property of the {{domxref("HTMLInputElement")}} interface gets and sets the action to be performed on an element being controlled by a button. For this to have an effect, [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget) must be set.
+
+It reflects the [`invokeaction`](/en-US/docs/Web/HTML/Element/button#invokeaction) HTML attribute.
+
+## Value
+
+A string.
+
+## Examples
+
+```js
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+toggleBtn.invokeAction = "showPopover";
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)

files/en-us/web/api/htmlinputelement/invoketargetelement/index.md

@@ -0,0 +1,38 @@
+---
+title: "HTMLInputElement: invokeTargetElement property"
+short-title: invokeTargetElement
+slug: Web/API/HTMLInputElement/invokeTargetElement
+page-type: web-api-instance-property
+browser-compat: api.HTMLInputElement.invokeTargetElement
+---
+
+{{ APIRef("DOM") }}
+
+The **`invokeTargetElement`** property of the {{domxref("HTMLInputElement")}} interface gets and sets the element to control via a button.
+
+It is the JavaScript equivalent of the [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget) HTML attribute.
+
+## Value
+
+A reference to an element in the DOM.
+
+## Examples
+
+```js
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggleBtn");
+
+toggleBtn.invokeTargetElement = popover;
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)

files/en-us/web/api/invokeevent/index.md

@@ -0,0 +1,71 @@
+---
+title: InvokeEvent
+slug: Web/API/InvokeEvent
+page-type: web-api-interface
+browser-compat: api.InvokeEvent
+---
+
+{{APIRef("UI Events")}}
+
+The **`InvokeEvent`** interface represents an event notifying the user when a [invoker control](/en-US/docs/Web/API/Invoker_API) is about to invoke an interactive element.
+
+It is the event object for the `HTMLElement` {{domxref("HTMLElement.invoke_event", "invoke")}} event, which fires elements from an Invoker Control, when the Invoker Control is interacted with (for example when it is clicked).
+
+{{InheritanceDiagram}}
+
+## Constructor
+
+- {{DOMxRef("InvokeEvent.InvokeEvent", "InvokeEvent()")}}
+  - : Creates an `InvokeEvent` object.
+
+## Instance properties
+
+_This interface inherits properties from its parent, {{DOMxRef("Event")}}._
+
+- {{DOMxRef("InvokeEvent.invoker")}} {{ReadOnlyInline}}
+  - : An Element representing the Invoker Control that caused this invocation.
+- {{DOMxRef("InvokeEvent.action")}} {{ReadOnlyInline}}
+  - : A string representing the action the element is about to take.
+
+## Examples
+
+### Basic example
+
+```js
+const popover = document.getElementById("mypopover");
+
+// ...
+
+popover.addEventListener("invoke", (event) => {
+  if (event.action === "show") {
+    console.log("Popover is about to be shown");
+  }
+});
+```
+
+### Custom example
+
+```js
+const customElement = document.querySelector("my-custom-element");
+
+// ...
+
+customElement.addEventListener("invoke", (event) => {
+  if (event.action === "spin") {
+    console.log("My own custom invoke behavior");
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Invokers API](/en-US/docs/Web/API/Invokers_API)
+- [`invoke` event](/en-US/docs/Web/API/HTMLElement/invoke_event)

files/en-us/web/api/invokers_api/index.md

@@ -0,0 +1,37 @@
+---
+title: Invokers API
+slug: Web/API/Invokers_API
+page-type: web-api-overview
+browser-compat: api.HTMLElement.invokers
+---
+
+{{DefaultAPISidebar("Invokers API")}}
+
+The **Invokers API** provides developers with a standard, consistent, flexible mechanism for controlling interactive HTML Elements on the page. Invokers allow for declaratively control using HTML attributes for equivalent JavaScript APIs.
+
+## Concepts and usage
+
+It is very common on the web to control interactive elements using {{htmlelement("button")}} elements, adding JavaScript event listeners to control what a button does when pressed. Invokers provide a declarative way to achieve the same effect for simple behaviors, such as toggling a popover, dialog, or details element.
+
+Invokers also allow for custom actions that can control behaviors using JavaScript without adding event listeners to the buttons.
+
+## HTML attributes
+
+- [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget)
+  - : Turns a {{htmlelement("button")}} or {{htmlelement("input")}} element into a Invoker control button; takes the ID of the element to control as its value.
+- [`invokeaction`](/en-US/docs/Web/HTML/Element/button#invokeaction)
+  - : Specifies the action to be performed on the element being controlled by an Invoker {{htmlelement("button")}} or {{htmlelement("input")}}.
+
+## Interfaces
+
+- {{domxref("InvokeEvent")}}
+  - : Represents an event notifying the user when an button is about to invoke an element. It is the event object for the {{domxref("HTMLElement.invoke_event", "invoke")}} event, which fires on the element to be invoked, when the button is interacted with.
+
+## Extensions to other interfaces
+
+### Instance properties
+
+- {{domxref("HTMLButtonElement.invokeTargetElement")}} and {{domxref("HTMLInputElement.invokeTargetElement")}}
+  - : Gets and sets the invoker element being controlled by the control button. The JavaScript equivalent of the [`invoketarget`](/en-US/docs/Web/HTML/Element/button#invoketarget) HTML attribute.
+- {{domxref("HTMLButtonElement.invokeAction")}} and {{domxref("HTMLInputElement.invokeAction")}}
+  - : Gets and sets the action to be performed on the invoker element being controlled by the control button. Reflects the value of the [`invokeraction`](/en-US/docs/Web/HTML/Element/button#invokeraction) HTML attribute.

files/en-us/web/html/element/button/index.md

@@ -72,6 +72,14 @@ This element's attributes include the [global attributes](/en-US/docs/Web/HTML/G
 
   - : The name of the button, submitted as a pair with the button's `value` as part of the form data, when that button is used to submit the form.
 
+- `invoketarget`
+
+  - : Turns a `<button>` element into an Invoker control button; takes the ID of the element to control as its value. See the {{domxref("Invokers API", "Invokers API", "", "nocode")}} landing page for more details.
+
+- `invokeaction`
+
+  - : Specifies the action to be performed on the element being controlled by an Invoker.
+
 - `popovertarget`
 
   - : Turns a `<button>` element into a popover control button; takes the ID of the popover element to control as its value. See the {{domxref("Popover API", "Popover API", "", "nocode")}} landing page for more details.

files/en-us/web/html/element/input/index.md

@@ -333,6 +333,8 @@ Attributes for the `<input>` element include the [global HTML attributes](/en-US
 | [`formmethod`](#formmethod)                   | `image`, `submit`                                                       | HTTP method to use for form submission                                                |
 | [`formnovalidate`](#formnovalidate)           | `image`, `submit`                                                       | Bypass form control validation for form submission                                    |
 | [`formtarget`](#formtarget)                   | `image`, `submit`                                                       | Browsing context for form submission                                                  |
+| [`invoketarget`](#invoketarget)               | `button`                                                                | Designates an `<input type="button">` as a control for an invoker element             |
+| [`invokeaction`](#invokeaction)               | `button`                                                                | Specifies the action to be performed on the element being controlled by an Invoker    |
 | [`height`](#height)                           | `image`                                                                 | Same as height attribute for {{htmlelement('img')}}; vertical dimension               |
 | [`list`](#list)                               | all except `hidden`, `password`, `checkbox`, `radio`, and buttons       | Value of the id attribute of the {{htmlelement('datalist')}} of autocomplete options  |
 | [`max`](#max)                                 | `date`, `month`, `week`, `time`, `datetime-local`, `number`, `range`    | Maximum value                                                                         |