@excom/event-handler 0.1.0

package/.rush/temp/chunked-rush-logs/event-handler.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/event-handler.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/event-handler.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 32.580141999999796
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 53.968691000000035
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 103.61115000000018
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/event-handler": "../../packages/event-handler:iu+Gwd294io6cbeYmVbBu6c2aWWWMg9YuILC/ZbWLyY=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/event-handler.ts

@@ -0,0 +1,178 @@
+import {
+  attributesToEntries,
+  attributesToObject,
+  Converter,
+  dashToCamel,
+  selectOne,
+  setAttr,
+} from "@excom/kit-utils";
+import { formToJson } from "@excom/kit-utils";
+import { ListenableElement } from "@excom/listenable-element";
+import { Neutron, TokenList } from "@excom/neutron";
+
+const attrFormatters = {
+  event: (attr: Attr): [string, string] => [
+    dashToCamel(attr.name.replace("detail-", "")),
+    attr.value,
+  ],
+  mutate: (attr: Attr): [string, string] => [
+    attr.name.replace("attr-", ""),
+    attr.value,
+  ],
+};
+
+/**
+ * Declarative bridge between DOM events and app actions. Listens (default
+ * `click`) and either fires custom events or invokes commands — built-in
+ * verbs (`show-modal`, `toggle-popover`) and the `--verb` commands elements
+ * handle — on any `target-ref` selector, where a `<button commandfor>` needs
+ * an id. Event payload comes from `detail-*` attributes and an optional
+ * `<form>` via `form-ref`.
+ *
+ * @summary Rewire clicks / inputs into events or commands.
+ *
+ * @example
+ * <event-handler fire-event="cart-add" detail-sku="sku-1">
+ *   Add to cart
+ * </event-handler>
+ */
+export const EventHandler = Neutron.compose([
+  ListenableElement,
+  Neutron({
+    tag: "event-handler",
+    props: {
+      /**
+       * @option
+       * Where outgoing events / mutations / commands apply. Unset = this
+       * element. Supports `:scope` for relative targeting (e.g.
+       * `:scope ~ dialog`).
+       * @values <CSS Selector>
+       */
+      targetRef: String,
+      /**
+       * @option
+       * Space-separated event names to dispatch on the target. Each name
+       * gets the same merged `detail`. Ignored when `mutate-target` is set.
+       * Pair with `detail-*` attributes for static detail fields.
+       * @values <EventName>…
+       */
+      fireEvent: TokenList,
+      /**
+       * @option
+       * Space-separated commands to invoke on the target: custom `--verb`
+       * commands (`--submit`, `--close`) dispatch a `command` event, as a
+       * `<button command commandfor>` would; built-in verbs (`show-modal`,
+       * `close`, `toggle-popover`) run through the platform.
+       * @values <command>…
+       */
+      commandName: TokenList,
+      /**
+       * @option
+       * Outgoing events use `bubbles: false` (default: bubble).
+       */
+      notBubbles: Boolean,
+      /**
+       * @option
+       * Outgoing events use `cancelable: false` (default: cancelable).
+       */
+      notCancelable: Boolean,
+      /**
+       * @option
+       * Outgoing events use `composed: false` (default: composed / cross
+       * shadow roots).
+       */
+      notComposed: Boolean,
+      /**
+       * @option
+       * `<form>` whose fields merge into event `detail`, or become
+       * attributes when `mutate-target` is set.
+       * @values <CSS Selector>
+       */
+      formRef: String,
+      /**
+       * @option
+       * @deprecated Write attributes on the target instead of firing events
+       * (sources: `attr-*` on this element plus `form-ref` fields). Use a
+       * Quark `@on <event> { … }` block instead — it writes State from the
+       * event without one element mutating another. Kept for
+       * compatibility; will be removed in a future major.
+       */
+      mutateTarget: Boolean,
+    },
+  }),
+])
+  .defineMethods({
+    actionHandler: (element) => {
+      const target = (
+        element.targetRef
+          ? selectOne(element.targetRef, {
+              scope: element,
+            })
+          : element
+      ) as HTMLElement;
+      /* `form-ref` → its values; `{}` unless it resolves to a `<form>` */
+      const formValues = (): Record<string, unknown> => {
+        const form = element.formRef
+          ? selectOne(element.formRef, { scope: element })
+          : null;
+        return form instanceof HTMLFormElement ? formToJson(form) : {};
+      };
+      if (
+        element.mutateTarget &&
+        target instanceof HTMLElement &&
+        target !== element
+      ) {
+        const formData = formValues();
+        [
+          ...Object.entries(formData || {}),
+          ...attributesToEntries(
+            element.attributes,
+            "attr-",
+            attrFormatters.mutate
+          ),
+        ].forEach(([key, value]) => {
+          const v = Converter.type(typeof value)?.prop.convert(value);
+          setAttr(target, key, v !== undefined ? v : value);
+        });
+      } else if (element.fireEvent?.length || element.commandName?.length) {
+        const { detail, ...otherFormData }: Record<string, unknown> =
+          formValues();
+        const detailObj = {
+          ...(detail || {}),
+          ...attributesToObject(
+            element.attributes,
+            "detail-",
+            attrFormatters.event
+          ),
+        };
+        return [
+          ...(element.commandName || [])?.map((commandName) => ({
+            command: [commandName, { target }],
+          })),
+          ...(element.fireEvent || [])?.map((eventName) => ({
+            emit: [
+              eventName,
+              {
+                bubbles: !element.notBubbles,
+                cancelable: !element.notCancelable,
+                composed: !element.notComposed,
+                ...(Object.keys(otherFormData || {}).length
+                  ? otherFormData
+                  : {}),
+                ...(Object.keys(detailObj).length ? { detail: detailObj } : {}),
+                target,
+              },
+            ],
+          })),
+        ];
+      }
+    },
+  })
+  .onConnected(
+    ({ listenFor, listenForLifecycle, handleEvent, isMoving }) =>
+      !isMoving &&
+      !listenFor?.length &&
+      !listenForLifecycle?.length && {
+        addListener: ["click", handleEvent],
+      }
+  );

package/index.css

@@ -0,0 +1,5 @@
+@import "./src/event-handler.css";
+
+@layer {
+  @mixin module-event-handler;
+}

package/index.ts

@@ -0,0 +1,17 @@
+import { EventHandler } from "./event-handler";
+
+EventHandler.define();
+
+export { EventHandler };
+
+type T_HTMLEventHandlerElement = typeof EventHandler.CustomElement;
+declare global {
+  interface HTMLEventHandlerElement extends T_HTMLEventHandlerElement {}
+  interface Window {
+    HTMLEventHandlerElement: HTMLEventHandlerElement;
+  }
+  interface HTMLElementTagNameMap {
+    "event-handler": HTMLEventHandlerElement;
+  }
+}
+export type { HTMLEventHandlerElement };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@excom/event-handler",
+  "version": "0.1.0",
+  "description": "<event-handler> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/listenable-element": "^0.1.0",
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/event-handler"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/event-handler/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "event-handler",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/event-handler.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/event-handler.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/event-handler.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/event-handler.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/event-handler.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/event-handler.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/src/event-handler.css

@@ -0,0 +1,19 @@
+@import "@excom/listenable-element/src/index.css";
+
+/**
+ * Styles for `<event-handler>`.
+ * @element event-handler
+ */
+
+/* Aliases */
+@custom-selector :--event-handler event-handler, .tag-event-handler;
+
+/**
+ * Skip the pointer cursor from the listenable mixin.
+ * @cssclass unstyled
+ */
+@define-mixin module-event-handler {
+  :--event-handler:not(.unstyled) {
+    @mixin listenable-element;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,245 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "event-handler.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "EventHandler",
+          "customElement": true,
+          "tagName": "event-handler",
+          "mixins": [
+            {
+              "name": "ListenableElement",
+              "package": "@excom/listenable-element"
+            }
+          ],
+          "summary": "Rewire clicks / inputs into events or commands.",
+          "description": "Declarative bridge between DOM events and app actions. Listens (default `click`) and either fires custom events or invokes commands — built-in verbs (`show-modal`, `toggle-popover`) and the `--verb` commands elements handle — on any `target-ref` selector, where a `<button commandfor>` needs an id. Event payload comes from `detail-*` attributes and an optional `<form>` via `form-ref`.",
+          "attributes": [
+            {
+              "name": "target-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "Where outgoing events / mutations / commands apply. Unset = this element. Supports `:scope` for relative targeting (e.g. `:scope ~ dialog`).",
+              "fieldName": "targetRef",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "fire-event",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Space-separated event names to dispatch on the target. Each name gets the same merged `detail`. Ignored when `mutate-target` is set. Pair with `detail-*` attributes for static detail fields.",
+              "fieldName": "fireEvent",
+              "values": [
+                "<EventName>…"
+              ]
+            },
+            {
+              "name": "command-name",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Space-separated commands to invoke on the target: custom `--verb` commands (`--submit`, `--close`) dispatch a `command` event, as a `<button command commandfor>` would; built-in verbs (`show-modal`, `close`, `toggle-popover`) run through the platform.",
+              "fieldName": "commandName",
+              "values": [
+                "<command>…"
+              ]
+            },
+            {
+              "name": "not-bubbles",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Outgoing events use `bubbles: false` (default: bubble).",
+              "fieldName": "notBubbles"
+            },
+            {
+              "name": "not-cancelable",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Outgoing events use `cancelable: false` (default: cancelable).",
+              "fieldName": "notCancelable"
+            },
+            {
+              "name": "not-composed",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Outgoing events use `composed: false` (default: composed / cross shadow roots).",
+              "fieldName": "notComposed"
+            },
+            {
+              "name": "form-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "`<form>` whose fields merge into event `detail`, or become attributes when `mutate-target` is set.",
+              "fieldName": "formRef",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "mutate-target",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "@deprecated Write attributes on the target instead of firing events (sources: `attr-*` on this element plus `form-ref` fields). Use a Quark `@on <event> { … }` 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"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "targetRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Where outgoing events / mutations / commands apply. Unset = this element. Supports `:scope` for relative targeting (e.g. `:scope ~ dialog`).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "fireEvent",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Space-separated event names to dispatch on the target. Each name gets the same merged `detail`. Ignored when `mutate-target` is set. Pair with `detail-*` attributes for static detail fields.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "commandName",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Space-separated commands to invoke on the target: custom `--verb` commands (`--submit`, `--close`) dispatch a `command` event, as a `<button command commandfor>` would; built-in verbs (`show-modal`, `close`, `toggle-popover`) run through the platform.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "notBubbles",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Outgoing events use `bubbles: false` (default: bubble).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "notCancelable",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Outgoing events use `cancelable: false` (default: cancelable).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "notComposed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Outgoing events use `composed: false` (default: composed / cross shadow roots).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "formRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "`<form>` whose fields merge into event `detail`, or become attributes when `mutate-target` is set.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "mutateTarget",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "@deprecated Write attributes on the target instead of firing events (sources: `attr-*` on this element plus `form-ref` fields). Use a Quark `@on <event> { … }` block instead — it writes State from the event without one element mutating another. Kept for compatibility; will be removed in a future major.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "_neutron": {
+            "cssClasses": [
+              {
+                "name": "unstyled",
+                "description": "Skip the pointer cursor from the listenable mixin."
+              }
+            ],
+            "cssAliases": [
+              {
+                "name": ":--event-handler",
+                "selectors": [
+                  "event-handler",
+                  ".tag-event-handler"
+                ],
+                "kind": "element"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "EventHandler",
+          "declaration": {
+            "name": "EventHandler",
+            "module": "event-handler.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "event-handler",
+          "declaration": {
+            "name": "EventHandler",
+            "module": "event-handler.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/command-dialog.html

@@ -0,0 +1,9 @@
+<section>
+  <event-handler target-ref=":scope + dialog" command-name="show-modal">
+    Open dialog
+  </event-handler>
+  <dialog>
+    Hello!
+    <form method="dialog"><button>Close</button></form>
+  </dialog>
+</section>

package/support/demos/debounce.html

@@ -0,0 +1,21 @@
+<div>
+  <section>
+    <event-handler listen-for="input" delay-ms="200" is-debounced fire-event="search-query" form-ref=":scope form">
+      <form>
+        <label>
+          <input name="detail.q" type="search" placeholder="Type to search…" />
+        </label>
+        <label>
+          Strict search
+          <input name="detail.strict" type="checkbox" role="switch" />
+        </label>
+      </form>
+    </event-handler>
+    <output>Waiting…</output>
+  </section>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    section { @on search-query (handle: setOutputFromDetail); }
+  </quark-sheet>
+</div>

package/support/demos/enter-close.html

@@ -0,0 +1,13 @@
+<section>
+  <event-handler target-ref=":scope + content-drawer" command-name="--open">
+    Open drawer
+  </event-handler>
+  <content-drawer id="demo-enter-close-drawer" is-open>
+    <event-handler listen-for="keydown" keycode-filter="enter" target-ref="#demo-enter-close-drawer" command-name="--close">
+      <label>
+        Favorite color
+        <input type="text" placeholder="Type something, then press Enter to close drawer" autofocus />
+      </label>
+    </event-handler>
+  </content-drawer>
+</section>

package/support/demos/escape-close.html

@@ -0,0 +1,16 @@
+<section>
+  <event-handler target-ref=":scope ~ dialog" command-name="show-modal">
+    Open dialog
+  </event-handler>
+  <event-handler
+    host-ref="window"
+    listen-for="keydown"
+    keycode-filter="escape"
+    target-ref=":scope ~ dialog"
+    command-name="close"
+  ></event-handler>
+  <dialog>
+    Press Escape anywhere to close.
+    <form method="dialog"><button>Close</button></form>
+  </dialog>
+</section>