@excom/event-handler 0.1.0

package/support/package-meta.json

@@ -0,0 +1,249 @@
+{
+  "shortName": "event-handler",
+  "package": {
+    "name": "@excom/event-handler",
+    "version": "0.1.0",
+    "description": "<event-handler> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "command-dialog": "<section>\n  <event-handler target-ref=\":scope + dialog\" command-name=\"show-modal\">\n    Open dialog\n  </event-handler>\n  <dialog>\n    Hello!\n    <form method=\"dialog\"><button>Close</button></form>\n  </dialog>\n</section>\n",
+    "debounce": "<div>\n  <section>\n    <event-handler listen-for=\"input\" delay-ms=\"200\" is-debounced fire-event=\"search-query\" form-ref=\":scope form\">\n      <form>\n        <label>\n          <input name=\"detail.q\" type=\"search\" placeholder=\"Type to search…\" />\n        </label>\n        <label>\n          Strict search\n          <input name=\"detail.strict\" type=\"checkbox\" role=\"switch\" />\n        </label>\n      </form>\n    </event-handler>\n    <output>Waiting…</output>\n  </section>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    section { @on search-query (handle: setOutputFromDetail); }\n  </quark-sheet>\n</div>",
+    "enter-close": "<section>\n  <event-handler target-ref=\":scope + content-drawer\" command-name=\"--open\">\n    Open drawer\n  </event-handler>\n  <content-drawer id=\"demo-enter-close-drawer\" is-open>\n    <event-handler listen-for=\"keydown\" keycode-filter=\"enter\" target-ref=\"#demo-enter-close-drawer\" command-name=\"--close\">\n      <label>\n        Favorite color\n        <input type=\"text\" placeholder=\"Type something, then press Enter to close drawer\" autofocus />\n      </label>\n    </event-handler>\n  </content-drawer>\n</section>\n",
+    "escape-close": "<section>\n  <event-handler target-ref=\":scope ~ dialog\" command-name=\"show-modal\">\n    Open dialog\n  </event-handler>\n  <event-handler\n    host-ref=\"window\"\n    listen-for=\"keydown\"\n    keycode-filter=\"escape\"\n    target-ref=\":scope ~ dialog\"\n    command-name=\"close\"\n  ></event-handler>\n  <dialog>\n    Press Escape anywhere to close.\n    <form method=\"dialog\"><button>Close</button></form>\n  </dialog>\n</section>\n",
+    "fire-event": "<div>\n  <section>\n    <event-handler fire-event=\"cart-add\" detail-sku=\"sku-1\">\n      Add to cart\n    </event-handler>\n    <output>Waiting…</output>\n  </section>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    section { @on cart-add (handle: setOutputFromDetail); }\n  </quark-sheet>\n</div>\n",
+    "prevent-default": "<event-handler prevent-default>\n  <a href=\"https://example.com\">This native link does nothing</a>\n</event-handler>\n",
+    "retarget": "<div>\n  <output>Waiting…</output>\n  <event-handler target-ref=\"output:has(+ :scope)\" fire-event=\"demo-ping\"\n    detail-label=\"pong\">\n    Ping previous output\n  </event-handler>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    output {\n      @on demo-ping (handle: setOutputFromDetail);\n    }\n  </quark-sheet>\n</div>\n",
+    "with-as": "<section>\n    <event-handler target-ref=\":scope + content-drawer\" command-name=\"--toggle\">\n        Toggle drawer\n    </event-handler>\n    <content-drawer>\n        <h2>Open!</h2>\n    </content-drawer>\n</section>\n"
+  },
+  "readme": "<h1 id=\"md-event-handler\">event-handler</h1>\n<p>Stitch behaviors of your app together, primarily through events.</p>\n<p><include-content data-demo=\"with-as\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Fire custom events</strong> Map any input event, such as clicks, or lifecycles to custom output events</li>\n<li><strong>Commands</strong> <code>command-name</code> invokes the HTML Command API — built-in verbs (<code>show-modal</code>) and the <code>--verb</code> commands elements accept (<code>--submit</code>, <code>--close</code>)</li>\n<li><strong>Retarget</strong> Aim events/commands at any selector (<code>target-ref</code>) — where a <code>&lt;button commandfor&gt;</code> needs an id</li>\n<li><strong>Global / host listening</strong> Listen to events globally or on any element. Helpful for: escape to dismiss, global shortcuts, etc.</li>\n<li><strong>Keycode filter</strong> Escape to dismiss, Shift+K shortcuts — keys / modifier chords</li>\n<li><strong>Listen filters</strong> Debounce, selector, and pathname gates</li>\n<li><strong>Custom Event Payloads</strong> <code>detail-*</code> attributes and forms convert to <code>event.detail</code> JSON</li>\n</ul>\n<blockquote>\n<p>In a view that already has a <code>&lt;quark-sheet&gt;</code>, the same wiring is a rule: <code>@on click (target: &quot;[data-add]&quot;) { @dispatch cart-add (detail: (sku: attr(&quot;data-sku&quot;))); }</code> — <code>@on</code> options cover <code>selector-filter</code> / <code>keycode-filter</code> / <code>is-debounced</code> / <code>host-ref</code>, and <code>@dispatch</code> / <code>@command</code> cover <code>fire-event</code> / <code>target-ref</code> / <code>form-ref</code> / <code>command-name</code>. Keep <code>&lt;event-handler&gt;</code> for markup without a sheet.</p>\n</blockquote>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Listen (default <code>click</code>), then either <code>fire-event</code> or <code>command-name</code>.</p>\n<include-content data-language=\"html\"><template>&lt;event-handler fire-event=\"cart-add\"&gt;\n  Add to cart\n&lt;/event-handler&gt;</template></include-content>\n<p>Or, for example: a successful form submit re-fetches the related data by invoking the provider&#39;s <code>--fetch</code> command.</p>\n<include-content data-language=\"html\"><template>&lt;event-handler listen-for=\"super-form-success\" target-ref=\"#fetch-todos\" command-name=\"--fetch\"&gt;\n  &lt;super-form&gt;\n    &lt;form&gt;\n      &lt;!-- form to create a new todo --&gt;\n    &lt;/form&gt;\n  &lt;/super-form&gt;\n&lt;/event-handler&gt;</template></include-content>\n<p>In a Nucleus Stack application, this will be one of the most heavily used elements. It is the primary method of linking a functional cause and effect.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-fire-a-custom-event\">Fire a custom event</h4>\n<p>Click dispatches <code>cart-add</code> event with <code>{ sku: &quot;sku-1&quot; }</code> in <code>event.detail</code>.</p>\n<p><include-content data-demo=\"fire-event\"></include-content></p>\n<h4 id=\"md-open-a-dialog\">Open a dialog</h4>\n<p><code>command-name</code> invokes the HTML Command API — here the built-in <code>show-modal</code> opens the sibling <code>&lt;dialog&gt;</code>. Custom commands (<code>command-name=&quot;--close&quot;</code>) reach any element that handles them, such as <code>&lt;content-drawer&gt;</code>, through a relative <code>target-ref</code>.</p>\n<p><include-content data-demo=\"command-dialog\"></include-content></p>\n<h4 id=\"md-close-on-enter\">Close on Enter</h4>\n<p><code>keycode-filter</code> gates keyboard handling — here Enter, focused in the\n<code>input</code>, invokes the drawer&#39;s <code>--close</code> command (local / bubbling events only).</p>\n<p><include-content data-demo=\"enter-close\"></include-content></p>\n<h4 id=\"md-escape-to-dismiss-global\">Escape to dismiss (global)</h4>\n<p><code>host-ref=&quot;window&quot;</code> listens for <code>keydown</code> on the window — Escape closes\nthe dialog even when focus is outside it.</p>\n<p><include-content data-demo=\"escape-close\"></include-content></p>\n<h4 id=\"md-cancel-a-link-click\">Cancel a link click</h4>\n<p><code>prevent-default</code> cancels the native action — here the wrapped <code>&lt;a&gt;</code> never navigates.\nUse <code>stop-propagation</code> / <code>stop-immediate-propagation</code> the same way when you need to stop bubbling.</p>\n<p><include-content data-demo=\"prevent-default\"></include-content></p>\n<h4 id=\"md-retarget\">Retarget</h4>\n<p><code>target-ref</code> aims the outgoing event at another element — useful when the target sits outside of the bubble path.</p>\n<p><include-content data-demo=\"retarget\"></include-content></p>\n<h4 id=\"md-debounced-input-form-data\">Debounced input / form data</h4>\n<p>Inherited <code>delay-ms</code> + <code>is-debounced</code> coalesce noisy <code>input</code> into one <code>search-query</code> event. Demo below is debounced every 200ms.</p>\n<p>Also demonstrated is form conversion into JSON: <code>text</code> -&gt; <code>string</code>, <code>checkbox</code> -&gt; <code>boolean</code>, etc. Including the data structure: <code>detail.strict</code> -&gt; <code>{detail: {strict}}</code>.</p>\n<p><include-content data-demo=\"debounce\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-event-handler\">event-handler</h1>\n<p>Stitch behaviors of your app together, primarily through events.</p>\n<p><include-content data-demo=\"with-as\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Fire custom events</strong> Map any input event, such as clicks, or lifecycles to custom output events</li>\n<li><strong>Commands</strong> <code>command-name</code> invokes the HTML Command API — built-in verbs (<code>show-modal</code>) and the <code>--verb</code> commands elements accept (<code>--submit</code>, <code>--close</code>)</li>\n<li><strong>Retarget</strong> Aim events/commands at any selector (<code>target-ref</code>) — where a <code>&lt;button commandfor&gt;</code> needs an id</li>\n<li><strong>Global / host listening</strong> Listen to events globally or on any element. Helpful for: escape to dismiss, global shortcuts, etc.</li>\n<li><strong>Keycode filter</strong> Escape to dismiss, Shift+K shortcuts — keys / modifier chords</li>\n<li><strong>Listen filters</strong> Debounce, selector, and pathname gates</li>\n<li><strong>Custom Event Payloads</strong> <code>detail-*</code> attributes and forms convert to <code>event.detail</code> JSON</li>\n</ul>\n<blockquote>\n<p>In a view that already has a <code>&lt;quark-sheet&gt;</code>, the same wiring is a rule: <code>@on click (target: &quot;[data-add]&quot;) { @dispatch cart-add (detail: (sku: attr(&quot;data-sku&quot;))); }</code> — <code>@on</code> options cover <code>selector-filter</code> / <code>keycode-filter</code> / <code>is-debounced</code> / <code>host-ref</code>, and <code>@dispatch</code> / <code>@command</code> cover <code>fire-event</code> / <code>target-ref</code> / <code>form-ref</code> / <code>command-name</code>. Keep <code>&lt;event-handler&gt;</code> for markup without a sheet.</p>\n</blockquote>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Listen (default <code>click</code>), then either <code>fire-event</code> or <code>command-name</code>.</p>\n<include-content data-language=\"html\"><template>&lt;event-handler fire-event=\"cart-add\"&gt;\n  Add to cart\n&lt;/event-handler&gt;</template></include-content>\n<p>Or, for example: a successful form submit re-fetches the related data by invoking the provider&#39;s <code>--fetch</code> command.</p>\n<include-content data-language=\"html\"><template>&lt;event-handler listen-for=\"super-form-success\" target-ref=\"#fetch-todos\" command-name=\"--fetch\"&gt;\n  &lt;super-form&gt;\n    &lt;form&gt;\n      &lt;!-- form to create a new todo --&gt;\n    &lt;/form&gt;\n  &lt;/super-form&gt;\n&lt;/event-handler&gt;</template></include-content>\n<p>In a Nucleus Stack application, this will be one of the most heavily used elements. It is the primary method of linking a functional cause and effect.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-fire-a-custom-event\">Fire a custom event</h4>\n<p>Click dispatches <code>cart-add</code> event with <code>{ sku: &quot;sku-1&quot; }</code> in <code>event.detail</code>.</p>\n<p><include-content data-demo=\"fire-event\"></include-content></p>\n<h4 id=\"md-open-a-dialog\">Open a dialog</h4>\n<p><code>command-name</code> invokes the HTML Command API — here the built-in <code>show-modal</code> opens the sibling <code>&lt;dialog&gt;</code>. Custom commands (<code>command-name=&quot;--close&quot;</code>) reach any element that handles them, such as <code>&lt;content-drawer&gt;</code>, through a relative <code>target-ref</code>.</p>\n<p><include-content data-demo=\"command-dialog\"></include-content></p>\n<h4 id=\"md-close-on-enter\">Close on Enter</h4>\n<p><code>keycode-filter</code> gates keyboard handling — here Enter, focused in the\n<code>input</code>, invokes the drawer&#39;s <code>--close</code> command (local / bubbling events only).</p>\n<p><include-content data-demo=\"enter-close\"></include-content></p>\n<h4 id=\"md-escape-to-dismiss-global\">Escape to dismiss (global)</h4>\n<p><code>host-ref=&quot;window&quot;</code> listens for <code>keydown</code> on the window — Escape closes\nthe dialog even when focus is outside it.</p>\n<p><include-content data-demo=\"escape-close\"></include-content></p>\n<h4 id=\"md-cancel-a-link-click\">Cancel a link click</h4>\n<p><code>prevent-default</code> cancels the native action — here the wrapped <code>&lt;a&gt;</code> never navigates.\nUse <code>stop-propagation</code> / <code>stop-immediate-propagation</code> the same way when you need to stop bubbling.</p>\n<p><include-content data-demo=\"prevent-default\"></include-content></p>\n<h4 id=\"md-retarget\">Retarget</h4>\n<p><code>target-ref</code> aims the outgoing event at another element — useful when the target sits outside of the bubble path.</p>\n<p><include-content data-demo=\"retarget\"></include-content></p>\n<h4 id=\"md-debounced-input-form-data\">Debounced input / form data</h4>\n<p>Inherited <code>delay-ms</code> + <code>is-debounced</code> coalesce noisy <code>input</code> into one <code>search-query</code> event. Demo below is debounced every 200ms.</p>\n<p>Also demonstrated is form conversion into JSON: <code>text</code> -&gt; <code>string</code>, <code>checkbox</code> -&gt; <code>boolean</code>, etc. Including the data structure: <code>detail.strict</code> -&gt; <code>{detail: {strict}}</code>.</p>\n<p><include-content data-demo=\"debounce\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/event-handler",
+    "shortName": "event-handler",
+    "version": "0.1.0",
+    "description": "<event-handler> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/event-handler@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/event-handler@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/event-handler"
+    },
+    "imports": {
+      "js": "import \"@excom/event-handler\";",
+      "css": "@import \"@excom/event-handler\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/event-handler\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/event-handler\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "event-handler",
+      "summary": "Rewire clicks / inputs into events or commands.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "command-name",
+          "type": "tokenlist",
+          "description": "Space-separated commands to invoke on the target: custom <code>--verb</code> commands (<code>--submit</code>, <code>--close</code>) dispatch a <code>command</code> event, as a <code>&lt;button command commandfor&gt;</code> would; built-in verbs (<code>show-modal</code>, <code>close</code>, <code>toggle-popover</code>) run through the platform.",
+          "fieldName": "commandName",
+          "surface": "option",
+          "values": "<command>…"
+        },
+        {
+          "name": "delay-ms",
+          "type": "number",
+          "description": "Delay handling by this many milliseconds.",
+          "fieldName": "delayMs",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "fire-event",
+          "type": "tokenlist",
+          "description": "Space-separated event names to dispatch on the target. Each name gets the same merged <code>detail</code>. Ignored when <code>mutate-target</code> is set. Pair with <code>detail-*</code> attributes for static detail fields.",
+          "fieldName": "fireEvent",
+          "surface": "option",
+          "values": "<EventName>…"
+        },
+        {
+          "name": "form-ref",
+          "type": "string",
+          "description": "<code>&lt;form&gt;</code> whose fields merge into event <code>detail</code>, or become attributes when <code>mutate-target</code> is set.",
+          "fieldName": "formRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "host-ref",
+          "type": "string",
+          "description": "Listen on another element / <code>window</code> / <code>document</code> — e.g. Escape to dismiss a dialog from a global <code>keydown</code>. Defaults to <code>:scope</code>. Used with <code>listen-for</code>. Not compatible with <code>listen-for-lifecycle</code>. The selector MUST resolve when <code>host-ref</code> is set — it will not wait for a match to appear.",
+          "fieldName": "hostRef",
+          "surface": "option",
+          "values": "<CSS Selector> | \"window\" | \"document\" | \"html\" | \"body\" | \"head\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "is-debounced",
+          "type": "boolean",
+          "description": "With <code>delay-ms</code>, coalesce bursts into one trailing call (debounce).",
+          "fieldName": "isDebounced",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "keycode-filter",
+          "type": "tokenlist",
+          "description": "Space-separated key filters (OR). Join modifiers with <code>+</code> (AND, any order): <code>shift+k tab</code> → Shift+K or Tab. Modifiers: <code>shift</code>, <code>alt</code>, <code>ctrl</code>/<code>control</code>, <code>meta</code>. Case-insensitive.",
+          "fieldName": "keycodeFilter",
+          "surface": "option",
+          "values": "<key | mod+key>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for",
+          "type": "tokenlist",
+          "description": "Space-separated event names to listen for. Defaults to <code>click</code> when unset (and no lifecycle list is set).",
+          "fieldName": "listenFor",
+          "surface": "option",
+          "values": "<EventName>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-for-lifecycle",
+          "type": "tokenlist",
+          "description": "Space-separated element lifecycles to handle.",
+          "fieldName": "listenForLifecycle",
+          "surface": "option",
+          "values": "\"connected\" | \"disconnected\" | \"adopted\"",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "listen-once",
+          "type": "boolean",
+          "description": "Handle each distinct event name / lifecycle at most once.",
+          "fieldName": "listenOnce",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "mutate-target",
+          "type": "boolean",
+          "description": "@deprecated Write attributes on the target instead of firing events (sources: <code>attr-*</code> on this element plus <code>form-ref</code> fields). Use a Quark <code>@on &lt;event&gt; { … }</code> block instead — it writes State from the event without one element mutating another. Kept for compatibility; will be removed in a future major.",
+          "fieldName": "mutateTarget",
+          "surface": "option"
+        },
+        {
+          "name": "not-bubbles",
+          "type": "boolean",
+          "description": "Outgoing events use <code>bubbles: false</code> (default: bubble).",
+          "fieldName": "notBubbles",
+          "surface": "option"
+        },
+        {
+          "name": "not-cancelable",
+          "type": "boolean",
+          "description": "Outgoing events use <code>cancelable: false</code> (default: cancelable).",
+          "fieldName": "notCancelable",
+          "surface": "option"
+        },
+        {
+          "name": "not-composed",
+          "type": "boolean",
+          "description": "Outgoing events use <code>composed: false</code> (default: composed / cross shadow roots).",
+          "fieldName": "notComposed",
+          "surface": "option"
+        },
+        {
+          "name": "pathname-filter",
+          "type": "tokenlist",
+          "description": "Only handle when <code>location.pathname</code> is one of these values — route-aware behaviors without a separate router element.",
+          "fieldName": "pathnameFilter",
+          "surface": "option",
+          "values": "<pathname>…",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "prevent-default",
+          "type": "boolean",
+          "description": "Call <code>preventDefault()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "preventDefault",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "selector-filter",
+          "type": "string",
+          "description": "Only handle events whose <code>event.target</code> matches this CSS selector. Does not support <code>:scope</code> in the selector.",
+          "fieldName": "selectorFilter",
+          "surface": "option",
+          "values": "<CSS Selector>",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-immediate-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopImmediatePropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopImmediatePropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "stop-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopPropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopPropagation",
+          "surface": "option",
+          "inheritedFrom": "@excom/listenable-element"
+        },
+        {
+          "name": "target-ref",
+          "type": "string",
+          "description": "Where outgoing events / mutations / commands apply. Unset = this element. Supports <code>:scope</code> for relative targeting (e.g. <code>:scope ~ dialog</code>).",
+          "fieldName": "targetRef",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "vibrate-ms",
+          "type": "number",
+          "description": "Vibrate on handle (<code>navigator.vibrate</code>). Empty / <code>0</code> uses a 20ms pulse.",
+          "fieldName": "vibrateMs",
+          "surface": "option",
+          "default": "\"20 (when attribute is present with no value)\"",
+          "inheritedFrom": "@excom/listenable-element"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [
+        {
+          "name": "unstyled",
+          "description": "Skip the pointer cursor from the listenable mixin."
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--event-handler",
+          "selectors": [
+            "event-handler",
+            ".tag-event-handler"
+          ],
+          "kind": "element",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/__snapshots__/debounce.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`debounce view > emits search-query after the debounce window > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 1,
+  "removeAttribute": 1,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 1,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/__snapshots__/fire-event.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`fire-event view > writes cart-add detail to output > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 0,
+  "removeAttribute": 0,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 0,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/__snapshots__/retarget.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`retarget view > pings the previous output > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 0,
+  "removeAttribute": 1,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 1,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/command-dialog.view.test.ts

@@ -0,0 +1,34 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("command-dialog view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("wires show-modal at the sibling dialog", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "command-dialog"));
+    const opener = root.querySelector("event-handler")!;
+    const dialog = root.querySelector("dialog")!;
+    expect(opener.getAttribute("command-name")).toBe("show-modal");
+    expect(opener.getAttribute("target-ref")).toBe(":scope + dialog");
+    expect(dialog.open).toBe(false);
+
+    click(opener);
+    await flush();
+    // happy-dom has no Command Invokers API (`button.command` /
+    // `commandForElement`), which is how event-handler invokes commands.
+    expect(dialog.open).toBe(false);
+  });
+});

package/support/tests/debounce.view.test.ts

@@ -0,0 +1,43 @@
+import "@excom/quark-sheet";
+import "../../index";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  expectComplexity,
+  flush,
+  installDemoModules,
+  measureComplexity,
+  mountView,
+  readDemo,
+  restoreDemoModules,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("debounce view", () => {
+  beforeEach(() => installDemoModules());
+  afterEach(() => {
+    document.body.innerHTML = "";
+    restoreDemoModules();
+  });
+
+  it("emits search-query after the debounce window", async () => {
+    const { root, quark } = await mountView(readDemo(import.meta.url, "debounce"));
+    const input = root.querySelector<HTMLInputElement>('input[name="detail.q"]')!;
+    input.value = "oak";
+    const meter = measureComplexity(quark!);
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    await flush();
+    expect(root.querySelector("output")?.textContent).toBe("Waiting…");
+    await wait(220);
+    await flush();
+    const budget = meter.take();
+    meter.stop();
+    expect(root.querySelector("output")?.textContent).toMatch(/oak/);
+    expectComplexity(budget);
+  });
+});

package/support/tests/enter-close.view.test.ts

@@ -0,0 +1,35 @@
+import "@excom/content-drawer";
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("enter-close view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("opens the drawer and closes on Enter", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "enter-close"));
+    const drawer = root.querySelector("content-drawer")!;
+    expect(drawer.hasAttribute("is-open")).toBe(true);
+    const input = root.querySelector("input")!;
+    input.dispatchEvent(
+      new KeyboardEvent("keydown", { bubbles: true, key: "Enter", keyCode: 13 }),
+    );
+    await flush();
+    expect(drawer.hasAttribute("is-open")).toBe(false);
+    click(root.querySelector("event-handler"));
+    await flush();
+    expect(drawer.hasAttribute("is-open")).toBe(true);
+  });
+});

package/support/tests/escape-close.view.test.ts

@@ -0,0 +1,44 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import {
+  click,
+  flush,
+  mountView,
+  readDemo,
+} from "@excom/quark/support/tests/view-helpers";
+
+describe("escape-close view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("wires show-modal and Escape-to-close commands", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "escape-close"));
+    const [opener, closer] = [...root.querySelectorAll("event-handler")];
+    const dialog = root.querySelector("dialog")!;
+    expect(opener.getAttribute("command-name")).toBe("show-modal");
+    expect(closer.getAttribute("command-name")).toBe("close");
+    expect(closer.getAttribute("host-ref")).toBe("window");
+    expect(closer.getAttribute("keycode-filter")).toBe("escape");
+
+    click(opener);
+    await flush();
+    // Same Command Invokers gap as command-dialog: click and Escape
+    // don't move `dialog.open` under happy-dom.
+    expect(dialog.open).toBe(false);
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        bubbles: true,
+        key: "Escape",
+        keyCode: 27,
+      }),
+    );
+    await flush();
+    expect(dialog.open).toBe(false);
+  });
+});

package/support/tests/event-handler.form-fallback.test.ts

@@ -0,0 +1,49 @@
+import { vi } from "vitest";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+/*
+ * `mutate-target` guards a form that yields no data. `formToJson` always
+ * returns an object for a real form, so stub the helper to reach the guard.
+ */
+vi.mock("@excom/kit-utils", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("@excom/kit-utils")>();
+  return {
+    ...actual,
+    formToJson: vi.fn(() => null),
+  };
+});
+
+import "../../index";
+
+describe("event-handler mutate-target with an empty form result", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("still writes attr-* attributes when the form yields nothing", () => {
+    fixture<HTMLDivElement>(
+      `<div id="mutate-empty-form"></div>
+       <event-handler
+         mutate-target
+         target-ref="#mutate-empty-form"
+         listen-for="my-event"
+         form-ref="form"
+         attr-data-state="open">
+           <form><input name="data-ignored" value="x" type="text"></form>
+       </event-handler>`,
+    );
+    const eventHandler = document.querySelector("event-handler")!;
+    eventHandler.dispatchEvent(new CustomEvent("my-event"));
+    const div = document.querySelector("#mutate-empty-form")!;
+    expect(div.getAttribute("data-state")).toBe("open");
+    expect(div.hasAttribute("data-ignored")).toBe(false);
+  });
+});