@excom/listenable-element 0.1.0

package/support/custom-elements.json

@@ -0,0 +1,332 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "index.ts",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "name": "ListenableElement",
+          "summary": "Declarative event / lifecycle listening for Neutron elements.",
+          "description": "Composition base that wires event and lifecycle listening. Subclasses implement `actionHandler`. Used by `<spa-a>`, `<event-handler>`, and similar interactive elements.",
+          "attributes": [
+            {
+              "name": "host-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear.",
+              "fieldName": "hostRef",
+              "values": [
+                "<CSS Selector>",
+                "window",
+                "document",
+                "html",
+                "body",
+                "head"
+              ]
+            },
+            {
+              "name": "listen-for",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set).",
+              "fieldName": "listenFor",
+              "values": [
+                "<EventName>…"
+              ]
+            },
+            {
+              "name": "listen-for-lifecycle",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Space-separated element lifecycles to handle.",
+              "fieldName": "listenForLifecycle",
+              "values": [
+                "connected",
+                "disconnected",
+                "adopted"
+              ]
+            },
+            {
+              "name": "listen-once",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Handle each distinct event name / lifecycle at most once.",
+              "fieldName": "listenOnce"
+            },
+            {
+              "name": "selector-filter",
+              "type": {
+                "text": "string"
+              },
+              "description": "Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector.",
+              "fieldName": "selectorFilter",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "keycode-filter",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive.",
+              "fieldName": "keycodeFilter",
+              "values": [
+                "<key",
+                "mod+key>…"
+              ]
+            },
+            {
+              "name": "pathname-filter",
+              "type": {
+                "text": "tokenlist"
+              },
+              "description": "Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element.",
+              "fieldName": "pathnameFilter",
+              "values": [
+                "<pathname>…"
+              ]
+            },
+            {
+              "name": "prevent-default",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Call `preventDefault()` on matched events (ignored for lifecycles).",
+              "fieldName": "preventDefault"
+            },
+            {
+              "name": "stop-propagation",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Call `stopPropagation()` on matched events (ignored for lifecycles).",
+              "fieldName": "stopPropagation"
+            },
+            {
+              "name": "stop-immediate-propagation",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Call `stopImmediatePropagation()` on matched events (ignored for lifecycles).",
+              "fieldName": "stopImmediatePropagation"
+            },
+            {
+              "name": "vibrate-ms",
+              "type": {
+                "text": "number"
+              },
+              "description": "Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse.",
+              "fieldName": "vibrateMs",
+              "default": "20 (when attribute is present with no value)"
+            },
+            {
+              "name": "delay-ms",
+              "type": {
+                "text": "number"
+              },
+              "description": "Delay handling by this many milliseconds.",
+              "fieldName": "delayMs"
+            },
+            {
+              "name": "is-debounced",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "With `delay-ms`, coalesce bursts into one trailing call (debounce).",
+              "fieldName": "isDebounced"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "hostRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "listenFor",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "listenForLifecycle",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Space-separated element lifecycles to handle.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "listenOnce",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Handle each distinct event name / lifecycle at most once.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "selectorFilter",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "keycodeFilter",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "pathnameFilter",
+              "type": {
+                "text": "tokenlist"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "preventDefault",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Call `preventDefault()` on matched events (ignored for lifecycles).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "stopPropagation",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Call `stopPropagation()` on matched events (ignored for lifecycles).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "stopImmediatePropagation",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Call `stopImmediatePropagation()` on matched events (ignored for lifecycles).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "vibrateMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse.",
+              "default": "20 (when attribute is present with no value)",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "delayMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Delay handling by this many milliseconds.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isDebounced",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "With `delay-ms`, coalesce bursts into one trailing call (debounce).",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ListenableElement",
+          "declaration": {
+            "name": "ListenableElement",
+            "module": "index.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/dist-docs/listenable-element.md

@@ -0,0 +1,122 @@
+# listenable-element
+
+Declarative event and lifecycle listening for Neutron elements —
+filter, debounce, vibrate, and hand off to your `actionHandler`.
+
+## Features
+
+- **Event / lifecycle hooks** Listen for DOM events or `connected` /
+  `disconnected` / `adopted`
+- **Host retarget** `host-ref="window"` / `document` / any selector —
+  Escape to dismiss, shortcuts outside the bubble path
+- **Target filters** Selector, keycode (`shift+k` chords), and pathname gates
+- **Debounce / delay** Coalesce noisy input
+- **Event hygiene** `prevent-default` / `stop-propagation` /
+  `stop-immediate-propagation`
+- **Haptic pulse** Optional `vibrate-ms` on handle
+
+## Installation
+
+
+`@excom/listenable-element` v0.1.0
+
+```bash
+pnpm add @excom/listenable-element
+```
+
+```bash
+npm install @excom/listenable-element
+```
+
+```bash
+yarn add @excom/listenable-element
+```
+
+### Import
+
+```ts
+import { /* … */ } from "@excom/listenable-element";
+```
+
+
+
+## Usage
+
+Compose `ListenableElement` and implement `actionHandler`. Concrete
+consumers include `<spa-a>` and `<event-handler>`.
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { ListenableElement } from "@excom/listenable-element";
+
+export const TapLog = Neutron.compose([
+  ListenableElement,
+  Neutron({ tag: "tap-log" }),
+])
+  .defineMethods({
+    actionHandler: (_el, e) => {
+      console.log("handled", e.type);
+    },
+  });
+
+TapLog.define();
+```
+
+```html
+<tap-log listen-for="click keydown" keycode-filter="enter">
+  Tap or Enter
+</tap-log>
+```
+
+`host-ref` moves listening off `:scope` — e.g. `host-ref="window"` for
+global keydown. See `<event-handler>` for Escape-to-dismiss examples.
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. |
+| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). |
+| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. |
+| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. |
+| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. |
+| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`. Case-insensitive. |
+| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. |
+| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). |
+| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). |
+| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). |
+| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. |
+| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. |
+| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). |
+
+
+
+### Examples
+
+#### Default click → navigate
+
+`<spa-a>` inherits this base and defaults to click when `listen-for`
+is unset:
+
+```html
+<spa-a route-href="/pricing">Pricing</spa-a>
+```
+
+#### Filter & debounce
+
+```html
+<event-handler
+  listen-for="input"
+  delay-ms="200"
+  is-debounced
+  fire-event="search-query"
+>
+  <input name="q" />
+</event-handler>
+```
+
+See `<event-handler>` and `<spa-a>` package docs for more examples
+built on this mixin.

package/support/docs/README.md

@@ -0,0 +1,82 @@
+# listenable-element
+
+Declarative event and lifecycle listening for Neutron elements —
+filter, debounce, vibrate, and hand off to your `actionHandler`.
+
+## Features
+
+- **Event / lifecycle hooks** Listen for DOM events or `connected` /
+  `disconnected` / `adopted`
+- **Host retarget** `host-ref="window"` / `document` / any selector —
+  Escape to dismiss, shortcuts outside the bubble path
+- **Target filters** Selector, keycode (`shift+k` chords), and pathname gates
+- **Debounce / delay** Coalesce noisy input
+- **Event hygiene** `prevent-default` / `stop-propagation` /
+  `stop-immediate-propagation`
+- **Haptic pulse** Optional `vibrate-ms` on handle
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Compose `ListenableElement` and implement `actionHandler`. Concrete
+consumers include `<spa-a>` and `<event-handler>`.
+
+```ts
+import { Neutron } from "@excom/neutron";
+import { ListenableElement } from "@excom/listenable-element";
+
+export const TapLog = Neutron.compose([
+  ListenableElement,
+  Neutron({ tag: "tap-log" }),
+])
+  .defineMethods({
+    actionHandler: (_el, e) => {
+      console.log("handled", e.type);
+    },
+  });
+
+TapLog.define();
+```
+
+```html
+<tap-log listen-for="click keydown" keycode-filter="enter">
+  Tap or Enter
+</tap-log>
+```
+
+`host-ref` moves listening off `:scope` — e.g. `host-ref="window"` for
+global keydown. See `<event-handler>` for Escape-to-dismiss examples.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Default click → navigate
+
+`<spa-a>` inherits this base and defaults to click when `listen-for`
+is unset:
+
+```html
+<spa-a route-href="/pricing">Pricing</spa-a>
+```
+
+#### Filter & debounce
+
+```html
+<event-handler
+  listen-for="input"
+  delay-ms="200"
+  is-debounced
+  fire-event="search-query"
+>
+  <input name="q" />
+</event-handler>
+```
+
+See `<event-handler>` and `<spa-a>` package docs for more examples
+built on this mixin.