From 65e171111e5e5c8174edb8c911a37e543792c569 Mon Sep 17 00:00:00 2001
From: Keith Cirkel <keithamus@users.noreply.github.com>
Date: Thu, 11 Jul 2024 16:24:45 +0100
Subject: [PATCH] update invokers using command nomenclature & semantics

BREAKING CHANGE:

This changes the polyfill to update to the latest names:

  invokeTargetElement->commandForElement
  invokeAction->command
  InvokeEvent->CommandEvent
  InvokeEvent#action->CommandEvent#command

This also prevents invokers functioning inside of forms without an
explicit `type=button`, additionally preventing form submissions from
firing if they have a `command`/`commandfor` attribute present.
---
 example.html |  45 ++++++------
 invoker.d.ts |  10 +--
 invoker.js   | 195 ++++++++++++++++++++++++++++++++++++++-------------
 3 files changed, 176 insertions(+), 74 deletions(-)
diff --git a/example.html b/example.html
index b174c12..74ab68b 100644
--- a/example.html
+++ b/example.html
@@ -13,23 +13,25 @@
   ></script>
   <script type="module" src="./invoker.js"></script>
   <body>
-    <h1>InvokeTarget &amp; InvokeAction</h1>
+    <h1>commandfor &amp; command attributes</h1>
     <p>
       This is a demonstration page for the
       <a href="https://github.com/keithamus/invokers-polyfill"
         >github:keithamus/invokers-polyfill</a
-      >.
+      >, which polyfills the <a href="https://open-ui.org/components/invokers.explainer/">
+        Invoker Buttons proposal
+      </a>
     </p>
     <hr />
     <h2>Initial Actions</h2>
-    <button invoketarget="my-dialog" interesttarget="dialog-explainer">
+    <button commandfor="my-dialog" command="showModal" interesttarget="dialog-explainer">
       This will open the dialog
     </button>
 
     <dialog id="my-dialog">
       <button
-        invoketarget="my-dialog"
-        invokeaction="close"
+        commandfor="my-dialog"
+        command="close"
         aria-label="Close dialog"
       >
         x
@@ -43,32 +45,30 @@ <h2>Initial Actions</h2>
 
     <hr />
 
-    <button invoketarget="my-popover-1">Opens a popover</button>
-
-    <button invoketarget="my-popover-1" invokeaction="togglePopover">
+    <button commandfor="my-popover-1" command="togglePopover">
       Toggles a popover
     </button>
 
     <div popover id="my-popover-1">
-      <button invoketarget="my-popover-1" invokeaction="hidePopover">X</button>
+      <button commandfor="my-popover-1" command="hidePopover">X</button>
       This is a popover
     </div>
     <hr />
 
     <details>
       <summary>Future Actions</summary>
-      <button invoketarget="my-file-input" invokeaction="showPicker">
+      <button commandfor="my-file-input" command="showPicker">
         This will open the file picker
       </button>
       <input type="file" id="my-file-input" />
       <hr />
-      <button invoketarget="my-date-input" invokeaction="showPicker">
+      <button commandfor="my-date-input" command="showPicker">
         This should open the date picker
       </button>
       <input type="date" id="my-date-input" />
       <hr />
 
-      <button invoketarget="my-details" interesttarget="button-explainer">
+      <button commandfor="my-details" command="open" interesttarget="button-explainer">
         This will open the details
       </button>
 
@@ -83,7 +83,7 @@ <h2>Initial Actions</h2>
 
       <hr />
 
-      <button invoketarget="my-select" invokeaction="showPicker" interesttarget="select-explainer">
+      <button commandfor="my-select" command="showPicker" interesttarget="select-explainer">
         This will open the select
       </button>
       <select id="my-select">
@@ -97,7 +97,8 @@ <h2>Initial Actions</h2>
       </div>
       <hr />
       <button
-        invoketarget="my-video"
+        commandfor="my-video"
+        command="playpause"
         interesttarget="my-video-playpause-explainer"
       >
         Play/pause
@@ -107,8 +108,8 @@ <h2>Initial Actions</h2>
         current state
       </div>
       <button
-        invoketarget="my-video"
-        invokeaction="play"
+        commandfor="my-video"
+        command="play"
         interesttarget="my-video-play-explainer"
       >
         Play
@@ -117,8 +118,8 @@ <h2>Initial Actions</h2>
         This button will cause the video to play if it isn't already
       </div>
       <button
-        invoketarget="my-video"
-        invokeaction="pause"
+        commandfor="my-video"
+        command="pause"
         interesttarget="my-video-pause-explainer"
       >
         Pause
@@ -127,8 +128,8 @@ <h2>Initial Actions</h2>
         This button will cause the video to pause if it isn't already
       </div>
       <button
-        invoketarget="my-video"
-        invokeaction="mute"
+        commandfor="my-video"
+        command="mute"
         interesttarget="my-video-mute-explainer"
       >
         Mute
@@ -138,8 +139,8 @@ <h2>Initial Actions</h2>
         state
       </div>
       <button
-        invoketarget="my-video"
-        invokeaction="requestfullscreen"
+        commandfor="my-video"
+        command="requestfullscreen"
         interesttarget="my-video-fullscreen-explainer"
       >
         Fullscreen
diff --git a/invoker.d.ts b/invoker.d.ts
index a75b34d..d853338 100644
--- a/invoker.d.ts
+++ b/invoker.d.ts
@@ -1,18 +1,18 @@
 interface InvokerMixin {
-  invokeTargetElement: HTMLElement | null;
-  invokeAction: string;
+  commandForElement: HTMLElement | null;
+  command: string;
 }
 
 declare global {
-  interface InvokeEvent extends Event {
+  interface CommandEvent extends Event {
     invoker: Element;
-    action: string;
+    command: string;
   }
   /* eslint-disable @typescript-eslint/no-empty-interface */
   interface HTMLButtonElement extends InvokerMixin {}
   interface HTMLInputElement extends InvokerMixin {}
   /* eslint-enable @typescript-eslint/no-empty-interface */
   interface Window {
-    InvokeEvent: InvokeEvent;
+    CommandEvent: CommandEvent;
   }
 }
diff --git a/invoker.js b/invoker.js
index 8cfe819..7ee108f 100644
--- a/invoker.js
+++ b/invoker.js
@@ -2,24 +2,40 @@
   if (
     typeof HTMLButtonElement === "undefined" ||
     typeof HTMLButtonElement.prototype !== "object" ||
-    "invokeTargetElement" in HTMLButtonElement.prototype
+    "commandForElement" in HTMLButtonElement.prototype
   ) {
     return;
   }
 
+  // XXX: Invoker Buttons used to dispatch 'invoke' events instead of
+  // 'command' events. We should ensure to prevent 'invoke' events being
+  // fired in those browsers.
   // XXX: https://bugs.chromium.org/p/chromium/issues/detail?id=1523183
   // Chrome will dispatch invoke events even with the flag disabled; so
   // we need to capture those to prevent duplicate events.
-  document.addEventListener('invoke', (e) => {
-    if (e.type == 'invoke' && e.isTrusted) {
-      e.stopImmediatePropagation();
-    }
-  }, true);
+  document.addEventListener(
+    "invoke",
+    (e) => {
+      if (e.type == "invoke" && e.isTrusted) {
+        e.stopImmediatePropagation();
+      }
+    },
+    true,
+  );
+  document.addEventListener(
+    "command",
+    (e) => {
+      if (e.type == "invoke" && e.isTrusted) {
+        e.stopImmediatePropagation();
+      }
+    },
+    true,
+  );
 
-  function makeEnumerable(obj, key) {
+  function enumerate(obj, key, enumerable = true) {
     Object.defineProperty(obj, key, {
       ...Object.getOwnPropertyDescriptor(obj, key),
-      enumerable: true,
+      enumerable,
     });
   }
 
@@ -36,22 +52,19 @@
   const invokeEventInvokers = new WeakMap();
   const invokeEventActions = new WeakMap();
 
-  class InvokeEvent extends Event {
+  class CommandEvent extends Event {
     constructor(type, invokeEventInit = {}) {
       super(type, invokeEventInit);
-      const { invoker, action } = invokeEventInit;
+      const { invoker, command } = invokeEventInit;
       if (invoker != null && !(invoker instanceof Element)) {
         throw new TypeError(`invoker must be an element`);
       }
       invokeEventInvokers.set(this, invoker || null);
-      invokeEventActions.set(
-        this,
-        action !== undefined ? String(action) : "",
-      );
+      invokeEventActions.set(this, command !== undefined ? String(command) : "");
     }
 
     get [Symbol.toStringTag]() {
-      return "InvokeEvent";
+      return "CommandEvent";
     }
 
     get invoker() {
@@ -67,33 +80,47 @@
       return invoker;
     }
 
-    get action() {
+    get command() {
       if (!invokeEventActions.has(this)) {
         throw new TypeError("illegal invocation");
       }
       return invokeEventActions.get(this);
     }
   }
-  makeEnumerable(InvokeEvent.prototype, "invoker");
-  makeEnumerable(InvokeEvent.prototype, "action");
+  enumerate(CommandEvent.prototype, "invoker");
+  enumerate(CommandEvent.prototype, "command");
+
+  class InvokeEvent extends Event {
+    constructor() {
+      throw new Error(
+        "InvokeEvent has been deprecated, it has been renamed to `ComamndEvent`",
+      );
+    }
+  }
 
   const invokerAssociatedElements = new WeakMap();
 
   function applyInvokerMixin(ElementClass) {
     Object.defineProperties(ElementClass.prototype, {
-      invokeTargetElement: {
+      commandForElement: {
         enumerable: true,
         configurable: true,
         set(targetElement) {
-          if (targetElement === null) {
-            this.removeAttribute("invoketarget");
-            invokerAssociatedElements.delete(this);
-          } else if (!(targetElement instanceof Element)) {
+          if (this.hasAttribute("invokeaction")) {
             throw new TypeError(
-              `invokeTargetElement must be an element or null`,
+              "Element has deprecated `invokeaction` attribute",
             );
+          } else if (this.hasAttribute("invoketarget")) {
+            throw new TypeError(
+              "Element has deprecated `invoketarget` attribute",
+            );
+          } else if (targetElement === null) {
+            this.removeAttribute("commandfor");
+            invokerAssociatedElements.delete(this);
+          } else if (!(targetElement instanceof Element)) {
+            throw new TypeError(`commandForElement must be an element or null`);
           } else {
-            this.setAttribute("invoketarget", "");
+            this.setAttribute("commandfor", "");
             const targetRootNode = getRootNode(targetElement);
             const thisRootNode = getRootNode(this);
             if (
@@ -110,6 +137,15 @@
           if (this.localName !== "button" && this.localName !== "input") {
             return null;
           }
+          if (
+            this.hasAttribute("invokeaction") ||
+            this.hasAttribute("invoketarget")
+          ) {
+            console.warn(
+              "Element has deprecated `invoketarget` or `invokeaction` attribute",
+            );
+            return null;
+          }
           if (
             this.localName === "input" &&
             this.type !== "reset" &&
@@ -121,7 +157,11 @@
           if (this.disabled) {
             return null;
           }
-          if (this.form && this.type === "submit") {
+          if (this.form && this.getAttribute("type") !== "button") {
+            console.warn(
+              "Element with `commandFor` is a form participant. " +
+                "It should explicitly set `type=button` in order for `commandFor` to work",
+            );
             return null;
           }
           const targetElement = invokerAssociatedElements.get(this);
@@ -134,7 +174,7 @@
             }
           }
           const root = getRootNode(this);
-          const idref = this.getAttribute("invoketarget");
+          const idref = this.getAttribute("commandfor");
           if (
             (root instanceof Document || root instanceof ShadowRoot) &&
             idref
@@ -144,16 +184,46 @@
           return null;
         },
       },
-      invokeAction: {
+      command: {
         enumerable: true,
         configurable: true,
         get() {
-          const value = this.getAttribute("invokeaction") || "";
+          const value = this.getAttribute("command") || "";
           if (value) return value;
           return "";
         },
         set(value) {
-          this.setAttribute("invokeaction", value);
+          this.setAttribute("command", value);
+        },
+      },
+
+      invokeAction: {
+        enumerable: false,
+        configurable: true,
+        get() {
+          throw new Error(
+            `invokeAction is deprecated. It has been renamed to command`,
+          );
+        },
+        set(value) {
+          throw new Error(
+            `invokeAction is deprecated. It has been renamed to command`,
+          );
+        },
+      },
+
+      invokeTargetElement: {
+        enumerable: false,
+        configurable: true,
+        get() {
+          throw new Error(
+            `invokeTargetElement is deprecated. It has been renamed to command`,
+          );
+        },
+        set(value) {
+          throw new Error(
+            `invokeTargetElement is deprecated. It has been renamed to command`,
+          );
         },
       },
     });
@@ -161,29 +231,57 @@
 
   function handleInvokerActivation(event) {
     if (event.defaultPrevented) return;
-    if (event.type !== 'click') return;
-    const invoker = event.target.closest('button[invoketarget], input[invoketarget]')
-    if (!invoker) return
+    if (event.type !== "click") return;
+    const oldInvoker = event.target.closest(
+      "button[invoketarget], button[invokeaction], input[invoketarget], input[invokeaction]",
+    );
+    if (oldInvoker) {
+      console.warn(
+        "Elements with `invoketarget` or `invokeaction` are deprecated and should be renamed to use `commandfor` and `command` respectively",
+      );
+    }
 
-    const invokee = invoker.invokeTargetElement;
-    const invokeEvent = new InvokeEvent("invoke", {
-      action: invoker.invokeAction,
+    const invoker = event.target.closest(
+      "button[commandfor], button[command], input[commandfor], input[command]",
+    );
+    if (!invoker) return;
+
+    if (this.form && this.getAttribute("type") !== "button") {
+      event.preventDefault();
+      throw new Error(
+        "Element with `commandFor` is a form participant. " +
+          "It should explicitly set `type=button` in order for `commandFor` to work. " +
+          "In order for it to act as a Submit button, it must not have command or commandfor attributes",
+      );
+    }
+
+    if (
+      invoker.hasAttribute("command") !== invoker.hasAttribute("commandfor")
+    ) {
+      const attr = invoker.hasAttribute("command") ? "command" : "commandfor";
+      const missing = invoker.hasAttribute("command")
+        ? "commandfor"
+        : "command";
+      throw new Error(
+        `Element with ${attr} attribute must also have a ${missing} attribute to functon.`,
+      );
+    }
+
+    const invokee = invoker.commandForElement;
+    const invokeEvent = new CommandEvent("command", {
+      command: invoker.command,
       invoker,
     });
     invokee.dispatchEvent(invokeEvent);
     if (invokeEvent.defaultPrevented) return;
 
-    const action = invokeEvent.action.toLowerCase();
+    const command = invokeEvent.command.toLowerCase();
 
     if (invokee.popover) {
       const canShow = !invokee.matches(":popover-open");
       const shouldShow =
-        canShow &&
-          (action === "" ||
-            action === "togglepopover" ||
-            action === "showpopover");
-      const shouldHide =
-        !canShow && (action === "" || action === "hidepopover");
+        canShow && (command === "togglepopover" || command === "showpopover");
+      const shouldHide = !canShow && command === "hidepopover";
 
       if (shouldShow) {
         invokee.showPopover();
@@ -192,10 +290,8 @@
       }
     } else if (invokee.localName === "dialog") {
       const canShow = !invokee.hasAttribute("open");
-      const shouldShow =
-        canShow && (action === "" || action === "showmodal");
-      const shouldHide =
-        !canShow && (action === "" || action === "close");
+      const shouldShow = canShow && command === "showmodal";
+      const shouldHide = !canShow && command === "close";
 
       if (shouldShow) {
         invokee.showModal();
@@ -233,6 +329,11 @@
 
   setupInvokeListeners(document);
 
+  Object.defineProperty(window, "CommandEvent", {
+    value: CommandEvent,
+    configurable: true,
+    writable: true,
+  });
   Object.defineProperty(window, "InvokeEvent", {
     value: InvokeEvent,
     configurable: true,
