@excom/listenable-element 0.1.0

package/support/package-meta.json

@@ -0,0 +1,148 @@
+{
+  "shortName": "listenable-element",
+  "package": {
+    "name": "@excom/listenable-element",
+    "version": "0.1.0",
+    "description": "ListenableElement base for Neutron elements",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "element-base"
+    }
+  },
+  "demos": {},
+  "readme": "<h1 id=\"md-listenable-element\">listenable-element</h1>\n<p>Declarative event and lifecycle listening for Neutron elements —\nfilter, debounce, vibrate, and hand off to your <code>actionHandler</code>.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Event / lifecycle hooks</strong> Listen for DOM events or <code>connected</code> /\n<code>disconnected</code> / <code>adopted</code></li>\n<li><strong>Host retarget</strong> <code>host-ref=&quot;window&quot;</code> / <code>document</code> / any selector —\nEscape to dismiss, shortcuts outside the bubble path</li>\n<li><strong>Target filters</strong> Selector, keycode (<code>shift+k</code> chords), and pathname gates</li>\n<li><strong>Debounce / delay</strong> Coalesce noisy input</li>\n<li><strong>Event hygiene</strong> <code>prevent-default</code> / <code>stop-propagation</code> /\n<code>stop-immediate-propagation</code></li>\n<li><strong>Haptic pulse</strong> Optional <code>vibrate-ms</code> on handle</li>\n</ul>\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>Compose <code>ListenableElement</code> and implement <code>actionHandler</code>. Concrete\nconsumers include <code>&lt;spa-a&gt;</code> and <code>&lt;event-handler&gt;</code>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { ListenableElement } from \"@excom/listenable-element\";\n\nexport const TapLog = Neutron.compose([\n  ListenableElement,\n  Neutron({ tag: \"tap-log\" }),\n])\n  .defineMethods({\n    actionHandler: (_el, e) =&gt; {\n      console.log(\"handled\", e.type);\n    },\n  });\n\nTapLog.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;tap-log listen-for=\"click keydown\" keycode-filter=\"enter\"&gt;\n  Tap or Enter\n&lt;/tap-log&gt;</template></include-content>\n<p><code>host-ref</code> moves listening off <code>:scope</code> — e.g. <code>host-ref=&quot;window&quot;</code> for\nglobal keydown. See <code>&lt;event-handler&gt;</code> for Escape-to-dismiss examples.</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-default-click-navigate\">Default click → navigate</h4>\n<p><code>&lt;spa-a&gt;</code> inherits this base and defaults to click when <code>listen-for</code>\nis unset:</p>\n<include-content data-language=\"html\"><template>&lt;spa-a route-href=\"/pricing\"&gt;Pricing&lt;/spa-a&gt;</template></include-content>\n<h4 id=\"md-filter-amp-debounce\">Filter &amp; debounce</h4>\n<include-content data-language=\"html\"><template>&lt;event-handler\n  listen-for=\"input\"\n  delay-ms=\"200\"\n  is-debounced\n  fire-event=\"search-query\"\n&gt;\n  &lt;input name=\"q\" /&gt;\n&lt;/event-handler&gt;</template></include-content>\n<p>See <code>&lt;event-handler&gt;</code> and <code>&lt;spa-a&gt;</code> package docs for more examples\nbuilt on this mixin.</p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-listenable-element\">listenable-element</h1>\n<p>Declarative event and lifecycle listening for Neutron elements —\nfilter, debounce, vibrate, and hand off to your <code>actionHandler</code>.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Event / lifecycle hooks</strong> Listen for DOM events or <code>connected</code> /\n<code>disconnected</code> / <code>adopted</code></li>\n<li><strong>Host retarget</strong> <code>host-ref=&quot;window&quot;</code> / <code>document</code> / any selector —\nEscape to dismiss, shortcuts outside the bubble path</li>\n<li><strong>Target filters</strong> Selector, keycode (<code>shift+k</code> chords), and pathname gates</li>\n<li><strong>Debounce / delay</strong> Coalesce noisy input</li>\n<li><strong>Event hygiene</strong> <code>prevent-default</code> / <code>stop-propagation</code> /\n<code>stop-immediate-propagation</code></li>\n<li><strong>Haptic pulse</strong> Optional <code>vibrate-ms</code> on handle</li>\n</ul>\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>Compose <code>ListenableElement</code> and implement <code>actionHandler</code>. Concrete\nconsumers include <code>&lt;spa-a&gt;</code> and <code>&lt;event-handler&gt;</code>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { ListenableElement } from \"@excom/listenable-element\";\n\nexport const TapLog = Neutron.compose([\n  ListenableElement,\n  Neutron({ tag: \"tap-log\" }),\n])\n  .defineMethods({\n    actionHandler: (_el, e) =&gt; {\n      console.log(\"handled\", e.type);\n    },\n  });\n\nTapLog.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;tap-log listen-for=\"click keydown\" keycode-filter=\"enter\"&gt;\n  Tap or Enter\n&lt;/tap-log&gt;</template></include-content>\n<p><code>host-ref</code> moves listening off <code>:scope</code> — e.g. <code>host-ref=&quot;window&quot;</code> for\nglobal keydown. See <code>&lt;event-handler&gt;</code> for Escape-to-dismiss examples.</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-default-click-navigate\">Default click → navigate</h4>\n<p><code>&lt;spa-a&gt;</code> inherits this base and defaults to click when <code>listen-for</code>\nis unset:</p>\n<include-content data-language=\"html\"><template>&lt;spa-a route-href=\"/pricing\"&gt;Pricing&lt;/spa-a&gt;</template></include-content>\n<h4 id=\"md-filter-amp-debounce\">Filter &amp; debounce</h4>\n<include-content data-language=\"html\"><template>&lt;event-handler\n  listen-for=\"input\"\n  delay-ms=\"200\"\n  is-debounced\n  fire-event=\"search-query\"\n&gt;\n  &lt;input name=\"q\" /&gt;\n&lt;/event-handler&gt;</template></include-content>\n<p>See <code>&lt;event-handler&gt;</code> and <code>&lt;spa-a&gt;</code> package docs for more examples\nbuilt on this mixin.</p>\n"
+  },
+  "installation": {
+    "name": "@excom/listenable-element",
+    "shortName": "listenable-element",
+    "version": "0.1.0",
+    "description": "ListenableElement base for Neutron elements",
+    "packageType": "element-base",
+    "install": {
+      "npm": "npm install @excom/listenable-element"
+    },
+    "imports": {
+      "js": "import { /* … */ } from \"@excom/listenable-element\";"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "summary": "Declarative event / lifecycle listening for Neutron elements.",
+      "kind": "mixin",
+      "attributes": [
+        {
+          "name": "delay-ms",
+          "type": "number",
+          "description": "Delay handling by this many milliseconds.",
+          "fieldName": "delayMs",
+          "surface": "option"
+        },
+        {
+          "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\""
+        },
+        {
+          "name": "is-debounced",
+          "type": "boolean",
+          "description": "With <code>delay-ms</code>, coalesce bursts into one trailing call (debounce).",
+          "fieldName": "isDebounced",
+          "surface": "option"
+        },
+        {
+          "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>…"
+        },
+        {
+          "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>…"
+        },
+        {
+          "name": "listen-for-lifecycle",
+          "type": "tokenlist",
+          "description": "Space-separated element lifecycles to handle.",
+          "fieldName": "listenForLifecycle",
+          "surface": "option",
+          "values": "\"connected\" | \"disconnected\" | \"adopted\""
+        },
+        {
+          "name": "listen-once",
+          "type": "boolean",
+          "description": "Handle each distinct event name / lifecycle at most once.",
+          "fieldName": "listenOnce",
+          "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>…"
+        },
+        {
+          "name": "prevent-default",
+          "type": "boolean",
+          "description": "Call <code>preventDefault()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "preventDefault",
+          "surface": "option"
+        },
+        {
+          "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>"
+        },
+        {
+          "name": "stop-immediate-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopImmediatePropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopImmediatePropagation",
+          "surface": "option"
+        },
+        {
+          "name": "stop-propagation",
+          "type": "boolean",
+          "description": "Call <code>stopPropagation()</code> on matched events (ignored for lifecycles).",
+          "fieldName": "stopPropagation",
+          "surface": "option"
+        },
+        {
+          "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)\""
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/listenable-element.matrix.test.ts

@@ -0,0 +1,300 @@
+import { ListenableElement } from "../../index";
+import { Neutron } from "@excom/neutron";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+const TAG = "listenable-matrix-test";
+if (!customElements.get(TAG)) {
+  ListenableElement.define(TAG);
+}
+
+/*
+ * Concrete consumer (README pattern) with `actionHandler` from construction,
+ * so connect-time lifecycles and `is-debounced` wrapping see a real handler,
+ * not one assigned after mount.
+ */
+const COMPOSED_TAG = "listenable-composed-test";
+const composedSpy = vi.fn();
+if (!customElements.get(COMPOSED_TAG)) {
+  Neutron.compose([ListenableElement, Neutron({ tag: COMPOSED_TAG })])
+    .defineMethods({
+      actionHandler: (_el, e: Event | string) => {
+        composedSpy(e);
+      },
+    })
+    .define();
+}
+
+const key = (k: string, init: KeyboardEventInit = {}) =>
+  new KeyboardEvent("keydown", { key: k, ...init });
+
+describe("ListenableElement keycode-filter matrix", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("matches alt / ctrl / control / meta chords", () => {
+    const el = fixture<any>(
+      `<${TAG} keycode-filter="alt+a ctrl+b control+c meta+d"></${TAG}>`,
+    );
+    const handler = vi.fn();
+    el.actionHandler = handler;
+
+    el.handleEvent(key("a", { altKey: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+    el.handleEvent(key("a"));
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    el.handleEvent(key("b", { ctrlKey: true }));
+    expect(handler).toHaveBeenCalledTimes(2);
+    el.handleEvent(key("c", { ctrlKey: true }));
+    expect(handler).toHaveBeenCalledTimes(3);
+    el.handleEvent(key("c", { shiftKey: true }));
+    expect(handler).toHaveBeenCalledTimes(3);
+
+    el.handleEvent(key("d", { metaKey: true }));
+    expect(handler).toHaveBeenCalledTimes(4);
+    el.handleEvent(key("d"));
+    expect(handler).toHaveBeenCalledTimes(4);
+  });
+
+  it("matches modifier-only tokens against the modifier keydown itself", () => {
+    const el = fixture<any>(
+      `<${TAG} keycode-filter="shift ctrl meta"></${TAG}>`,
+    );
+    const handler = vi.fn();
+    el.actionHandler = handler;
+
+    el.handleEvent(key("Shift", { shiftKey: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+    // `ctrl` is spelled `Control` on the event
+    el.handleEvent(key("Control", { ctrlKey: true }));
+    expect(handler).toHaveBeenCalledTimes(2);
+    el.handleEvent(key("Meta", { metaKey: true }));
+    expect(handler).toHaveBeenCalledTimes(3);
+    // a modifier that is not in the filter
+    el.handleEvent(key("Alt", { altKey: true }));
+    expect(handler).toHaveBeenCalledTimes(3);
+    // the modifier is held but a different key was pressed
+    el.handleEvent(key("x", { shiftKey: true }));
+    expect(handler).toHaveBeenCalledTimes(3);
+  });
+
+  it("accepts the `control` spelling for a modifier-only token", () => {
+    const el = fixture<any>(`<${TAG} keycode-filter="control"></${TAG}>`);
+    const handler = vi.fn();
+    el.actionHandler = handler;
+    el.handleEvent(key("Control", { ctrlKey: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+    el.handleEvent(key("Shift", { shiftKey: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("never matches an empty token or a keyless event", () => {
+    const el = fixture<any>(`<${TAG} keycode-filter="+"></${TAG}>`);
+    const handler = vi.fn();
+    el.actionHandler = handler;
+    el.handleEvent(key("a"));
+    el.handleEvent(key("+"));
+    expect(handler).not.toHaveBeenCalled();
+
+    el.keycodeFilter = ["a"];
+    // no `key` at all (e.g. a synthetic event)
+    el.handleEvent(new KeyboardEvent("keydown"));
+    expect(handler).not.toHaveBeenCalled();
+    el.handleEvent(key("a"));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("ListenableElement listen-for defaults", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("falls back to click when listen-for is cleared later", () => {
+    // Bare base adds nothing until `listen-for` / `host-ref` changes.
+    // `<event-handler>` adds the connect-time click default.
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    const handler = vi.fn();
+    el.actionHandler = handler;
+    expect(el).toContainListeners({ click: 0 });
+
+    el.listenFor = ["foo-event"];
+    expect(el).toContainListeners({ click: 0, "foo-event": 1 });
+    el.click();
+    expect(handler).not.toHaveBeenCalled();
+    el.dispatchEvent(new CustomEvent("foo-event"));
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    // clearing the list falls back to the click default
+    el.listenFor = [];
+    expect(el).toContainListeners({ click: 1, "foo-event": 0 });
+    el.click();
+    expect(handler).toHaveBeenCalledTimes(2);
+
+    // and the click default is what gets removed on the next change
+    el.listenFor = ["bar-event"];
+    expect(el).toContainListeners({ click: 0, "bar-event": 1 });
+    el.click();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses the default click listener on a host-ref target", () => {
+    const button = fixture<HTMLButtonElement>(
+      `<button id="default-host"></button>`,
+    );
+    const el = fixture<any>(`<${TAG} host-ref="#default-host"></${TAG}>`);
+    const handler = vi.fn();
+    el.actionHandler = handler;
+    expect(button).toContainListeners({ click: 1 });
+    expect(el).toContainListeners({ click: 0 });
+
+    button.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    el.hostRef = null;
+    expect(button).toContainListeners({ click: 0 });
+    expect(el).toContainListeners({ click: 1 });
+    button.click();
+    expect(handler).toHaveBeenCalledTimes(1);
+    el.click();
+    expect(handler).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("ListenableElement is-debounced", () => {
+  beforeEach(() => composedSpy.mockClear());
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("wraps actionHandler in a trailing debounce when delay-ms is set", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for="ping-event" delay-ms="40" is-debounced></${COMPOSED_TAG}>`,
+    );
+    expect(typeof el.debouncedActionHandler).toBe("function");
+
+    el.dispatchEvent(new CustomEvent("ping-event"));
+    el.dispatchEvent(new CustomEvent("ping-event"));
+    el.dispatchEvent(new CustomEvent("ping-event"));
+    expect(composedSpy).not.toHaveBeenCalled();
+    await wait(60);
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+
+    /* Turning it off doesn't throw. Neutron treats an effect on a
+       Function-typed prop that already holds a function as a method
+       call, so the wrapper isn't actually replaced here. See the report. */
+    expect(() => {
+      el.isDebounced = false;
+    }).not.toThrow();
+    expect(el.isDebounced).toBe(false);
+    el.dispatchEvent(new CustomEvent("ping-event"));
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+    await wait(60);
+    expect(composedSpy.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("falls back to a 10ms debounce window without delay-ms", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for="ping-event" is-debounced></${COMPOSED_TAG}>`,
+    );
+    expect(typeof el.debouncedActionHandler).toBe("function");
+    // without delay-ms the element handles synchronously (the wrapper is
+    // only consulted when a delay is configured)
+    el.dispatchEvent(new CustomEvent("ping-event"));
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("ListenableElement lifecycles", () => {
+  beforeEach(() => composedSpy.mockClear());
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("handles connected on mount, ignores synchronous moves, re-handles on reconnect", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for-lifecycle="connected"></${COMPOSED_TAG}>`,
+    );
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+    expect(composedSpy).toHaveBeenCalledWith("connected");
+    expect(el._lifecycleTracker).toEqual(["connected"]);
+
+    // a synchronous re-parent is a move, not a fresh connection
+    const other = document.createElement("div");
+    document.body.appendChild(other);
+    other.appendChild(el);
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+
+    // a real disconnect followed by a later reconnect handles again
+    el.remove();
+    await wait(0);
+    document.body.appendChild(el);
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("handles connected only once with listen-once", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for-lifecycle="connected" listen-once></${COMPOSED_TAG}>`,
+    );
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+    el.remove();
+    await wait(0);
+    document.body.appendChild(el);
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("handles the adopted lifecycle", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for-lifecycle="adopted"></${COMPOSED_TAG}>`,
+    );
+    expect(composedSpy).not.toHaveBeenCalled();
+
+    // happy-dom never runs `adoptedCallback` (`adoptNode` skips CE
+    // reactions), so drive the platform hook directly.
+    el.adoptedCallback();
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+    expect(composedSpy).toHaveBeenCalledWith("adopted");
+    expect(el._lifecycleTracker).toEqual(["adopted"]);
+
+    // `isAdopted` resets on disconnect, so a later adoption handles again
+    el.remove();
+    await wait(0);
+    document.body.appendChild(el);
+    await wait(0);
+    el.adoptedCallback();
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("ignores lifecycles that are not listed", async () => {
+    const el = fixture<any>(
+      `<${COMPOSED_TAG} listen-for-lifecycle="disconnected"></${COMPOSED_TAG}>`,
+    );
+    expect(composedSpy).not.toHaveBeenCalled();
+    el.adoptedCallback();
+    await wait(0);
+    expect(composedSpy).not.toHaveBeenCalled();
+    el.remove();
+    await wait(0);
+    expect(composedSpy).toHaveBeenCalledTimes(1);
+    expect(composedSpy).toHaveBeenCalledWith("disconnected");
+  });
+});