dom-primitive-bindings 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 KeshavSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# DOM Primitive Bindings
+
+> Modern, lightweight, delegated event engine for browser DOMs. Attach exactly one listener per event type to any container; let bubbling handle matching, runners, and extraction with zero re-binding overhead.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+[![Single Source of Truth](https://img.shields.io/badge/Version-v1-blue.svg)]()
+
+---
+
+## 🎯 The Core Concept
+
+Traditional client-side code attaches listeners to every button, link, and input. When tables are refreshed, cards are added, or modals render dynamic markup, those listeners break or leak memory unless manually re-attached.
+
+**DOM Primitive Bindings** inverts the architecture:
+- Attach **one listener** per event type to the parent container (`table`, `form`, `card-grid`).
+- As events bubble up, `closest(selector)` identifies target elements.
+- The associated `runner` executes and forwards data cleanly to `onExtract`.
+- Dynamically created DOM elements are supported immediately with **zero re-binding**.
+
+---
+
+## 🏗️ Staged Architecture (`src/v1/`)
+
+The repository strictly enforces a staged pipeline where every directory contains an `index.js` and all files export a single function as `default`:
+
+```text
+src/
+└── v1/
+    ├── guards/               # Validates container and bindings array
+    │   ├── container/        # Validates and resolves 1st input (container / ID)
+    │   ├── bindings/         # Validates 2nd input (bindings array)
+    │   └── index.js
+    ├── prepare/              # Groups bindings by event type into Map
+    │   ├── groupBindings.js
+    │   └── index.js
+    ├── listeners/            # Attaches single listener per event type to container
+    │   ├── attachListener.js
+    │   └── index.js
+    ├── dispatch/             # Handles event bubbling, runner execution & extraction
+    │   ├── getStartInput.js
+    │   ├── getClientData.js
+    │   ├── executeBinding.js
+    │   └── index.js
+    ├── register/             # Exposes module onto window.ks.domPrimitiveBindings
+    │   ├── meta.js
+    │   └── index.js
+    └── index.js              # Orchestrator exporting bindEvents
+```
+
+### Key Design Disciplines
+1. **Zero Comments:** The folder hierarchy and descriptive file names convey the full narrative without inline code comments.
+2. **Folder Discipline:** Every folder contains an `index.js` public gateway.
+3. **Single Function Default Export:** No default export objects; every file exports a single function.
+
+---
+
+## 🚀 Interactive Browser Samples (`samples/v1/`)
+
+Start the Vite development server to view and interact with real browser DOM events:
+
+```bash
+npm install
+npm run dev
+```
+
+Open in Chrome or Edge:
+- **`samples/v1/tableWithSearch/`** — Delegated table row clicks and live Enter-key search input.
+- **`samples/v1/cardGrid/`** — Dynamic card insertion into DOM with instant delegated action buttons.
+- **`samples/v1/formEvents/`** — Live form field inputs, dropdown selection changes, and submit/clear buttons.
+
+---
+
+## 📦 Usage
+
+### Browser (ES Module / Script)
+
+```html
+<script type="module" src="./docs/dist/v1/min.js"></script>
+<script type="module">
+  const bindings = [
+    {
+      event: "click",
+      selector: ".btn-cart",
+      runner: (target) => ({ productId: target.dataset.id }),
+      onExtract: (data) => console.log("Added to cart:", data)
+    }
+  ];
+
+  window.ks.domPrimitiveBindings.bindEvents("products-container", bindings);
+</script>
+```
+
+### Module Import
+
+```javascript
+import { bindEvents } from "dom-primitive-bindings";
+
+bindEvents(containerElement, [
+  {
+    event: "click",
+    selector: ".action-btn",
+    runner: (btn) => btn.dataset.action,
+    onExtract: (action) => console.log("Action:", action)
+  }
+]);
+```
+
+---
+
+## 🧪 Testing & Build
+
+```bash
+# Run unit tests
+npm test
+
+# Build production bundle to docs/dist/v1/min.js
+npm run build
+```
+
+---
+
+## 📄 License
+
+MIT © KeshavSoft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/docs/dist/min.js

@@ -0,0 +1,63 @@
+const u = {
+  name: "dom-primitive-bindings",
+  version: "1.0.0"
+}, c = (t, n = u) => {
+  if (!(!t || typeof globalThis > "u"))
+    return globalThis.ks ?? (globalThis.ks = {}), globalThis.ks.domPrimitiveBindings = {
+      meta: n,
+      bindEvents: t
+    }, globalThis.ks.domPrimitiveBindings;
+}, l = (t) => typeof t == "string" ? document.getElementById(t) || document.querySelector(t) : t && typeof t == "object" && "addEventListener" in t ? t : null, a = (t) => {
+  if (!t) return null;
+  const n = l(t);
+  return n || null;
+}, f = (t) => Array.isArray(t) ? t.filter((n) => n && typeof n == "object" && typeof n.event == "string" && typeof n.selector == "string") : [], g = (t) => {
+  const n = f(t);
+  return n.length === 0 ? null : n;
+}, p = (t, n) => {
+  const e = a(t);
+  if (!e) return null;
+  const r = g(n);
+  return r ? { container: e, bindings: r } : null;
+}, d = (t) => {
+  const n = /* @__PURE__ */ new Map();
+  for (const e of t) {
+    const r = n.get(e.event) ?? [];
+    r.push(e), n.set(e.event, r);
+  }
+  return n;
+}, y = (t) => d(t), m = (t, n, e) => {
+  var r;
+  return t.root === "event" || (r = n == null ? void 0 : n.type) != null && r.startsWith("key") ? n : e;
+}, h = (t, n, e) => ({
+  ...t.clientData,
+  event: n,
+  targetElement: e
+}), v = ({ binding: t, event: n, matchElement: e }) => {
+  const r = m(t, n, e), i = h(t, n, e), o = t.runner, s = typeof o == "function" ? o(r, t.instructions, i) : r;
+  return s != null && typeof t.onExtract == "function" && t.onExtract(s, n, e), s;
+}, B = ({ bindings: t, event: n, container: e }) => {
+  var r, i;
+  for (const o of t) {
+    const s = (i = (r = n.target) == null ? void 0 : r.closest) == null ? void 0 : i.call(r, o.selector);
+    !s || !e.contains(s) || v({ binding: o, event: n, matchElement: s });
+  }
+}, E = (t, n, e) => {
+  t.addEventListener(n, (r) => {
+    B({ bindings: e, event: r, container: t });
+  });
+}, k = (t, n) => {
+  for (const [e, r] of n.entries())
+    E(t, e, r);
+  return t;
+}, T = (t, n = []) => {
+  const e = p(t, n);
+  if (!e) return null;
+  const { container: r, bindings: i } = e, o = y(i);
+  return k(r, o), r;
+};
+c(T);
+export {
+  T as bindEvents,
+  T as default
+};

package/docs/dist/v1/min.js

@@ -0,0 +1,63 @@
+const u = {
+  name: "dom-primitive-bindings",
+  version: "1.0.0"
+}, c = (t, n = u) => {
+  if (!(!t || typeof globalThis > "u"))
+    return globalThis.ks ?? (globalThis.ks = {}), globalThis.ks.domPrimitiveBindings = {
+      meta: n,
+      bindEvents: t
+    }, globalThis.ks.domPrimitiveBindings;
+}, l = (t) => typeof t == "string" ? document.getElementById(t) || document.querySelector(t) : t && typeof t == "object" && "addEventListener" in t ? t : null, a = (t) => {
+  if (!t) return null;
+  const n = l(t);
+  return n || null;
+}, f = (t) => Array.isArray(t) ? t.filter((n) => n && typeof n == "object" && typeof n.event == "string" && typeof n.selector == "string") : [], g = (t) => {
+  const n = f(t);
+  return n.length === 0 ? null : n;
+}, p = (t, n) => {
+  const e = a(t);
+  if (!e) return null;
+  const r = g(n);
+  return r ? { container: e, bindings: r } : null;
+}, d = (t) => {
+  const n = /* @__PURE__ */ new Map();
+  for (const e of t) {
+    const r = n.get(e.event) ?? [];
+    r.push(e), n.set(e.event, r);
+  }
+  return n;
+}, y = (t) => d(t), m = (t, n, e) => {
+  var r;
+  return t.root === "event" || (r = n == null ? void 0 : n.type) != null && r.startsWith("key") ? n : e;
+}, h = (t, n, e) => ({
+  ...t.clientData,
+  event: n,
+  targetElement: e
+}), v = ({ binding: t, event: n, matchElement: e }) => {
+  const r = m(t, n, e), i = h(t, n, e), o = t.runner, s = typeof o == "function" ? o(r, t.instructions, i) : r;
+  return s != null && typeof t.onExtract == "function" && t.onExtract(s, n, e), s;
+}, B = ({ bindings: t, event: n, container: e }) => {
+  var r, i;
+  for (const o of t) {
+    const s = (i = (r = n.target) == null ? void 0 : r.closest) == null ? void 0 : i.call(r, o.selector);
+    !s || !e.contains(s) || v({ binding: o, event: n, matchElement: s });
+  }
+}, E = (t, n, e) => {
+  t.addEventListener(n, (r) => {
+    B({ bindings: e, event: r, container: t });
+  });
+}, k = (t, n) => {
+  for (const [e, r] of n.entries())
+    E(t, e, r);
+  return t;
+}, T = (t, n = []) => {
+  const e = p(t, n);
+  if (!e) return null;
+  const { container: r, bindings: i } = e, o = y(i);
+  return k(r, o), r;
+};
+c(T);
+export {
+  T as bindEvents,
+  T as default
+};

package/docs/index.html

@@ -0,0 +1,185 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>DOM Primitive Bindings (v1) — Architecture & Story</title>
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css" rel="stylesheet">
+  <style>
+    body {
+      background-color: #f8fafc;
+      color: #334155;
+      font-family: system-ui, -apple-system, sans-serif;
+      line-height: 1.6;
+    }
+    .hero-banner {
+      background: linear-gradient(135deg, #065f46 0%, #047857 100%);
+      color: #ffffff;
+      padding: 56px 0;
+      margin-bottom: 40px;
+    }
+    .feature-card {
+      background: #ffffff;
+      border: 1px solid #e2e8f0;
+      border-radius: 12px;
+      padding: 24px;
+      height: 100%;
+    }
+    pre {
+      background-color: #0f172a;
+      color: #f1f5f9;
+      padding: 16px;
+      border-radius: 8px;
+      font-size: 0.9rem;
+      overflow-x: auto;
+    }
+    code:not(pre code) {
+      background-color: #e2e8f0;
+      color: #0f172a;
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-size: 0.88em;
+    }
+  </style>
+</head>
+
+<body>
+
+  <header class="hero-banner shadow-sm">
+    <div class="container">
+      <div class="d-flex align-items-center justify-content-between flex-wrap gap-3">
+        <div>
+          <span class="badge bg-warning text-dark mb-2">v1 · Delegated Event Engine</span>
+          <h1 class="display-6 fw-bold mb-2">DOM Primitive Bindings</h1>
+          <p class="lead mb-0 text-white opacity-75">
+            Single-listener container delegation with zero overhead. Modern, declarative, and dynamic.
+          </p>
+        </div>
+        <div class="d-flex gap-2">
+          <a href="../samples/v1/index.html" class="btn btn-outline-light btn-sm">
+            <i class="bi bi-play-circle me-1"></i> Interactive Samples
+          </a>
+          <a href="../index.html" class="btn btn-light btn-sm text-dark">
+            <i class="bi bi-house me-1"></i> Home
+          </a>
+        </div>
+      </div>
+    </div>
+  </header>
+
+  <main class="container pb-5" style="max-width: 1000px;">
+
+    <!-- Section 1: The Core Mental Model -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-3">
+        <i class="bi bi-diagram-3-fill text-success me-2"></i> The Event Delegation Story
+      </h2>
+      <p>
+        Traditional web apps attach <code>addEventListener</code> to individual buttons, inputs, and rows. When rows are re-rendered, paginated, or filtered, listeners are either lost or accidentally duplicated, creating memory leaks and stale event handlers.
+      </p>
+      <p class="mb-0">
+        <strong>DOM Primitive Bindings</strong> inverts this pattern. Exactly <strong>one listener per event type</strong> is attached to the parent container (e.g. <code>#table-container</code> or <code>#form-container</code>). When an event occurs, it bubbles to the container, checks for matched selectors via <code>closest(selector)</code>, and dispatches to the registered runner. New DOM elements added at runtime work immediately with zero re-binding!
+      </p>
+    </section>
+
+    <!-- Section 2: Staged Architecture -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-3">
+        <i class="bi bi-layers-fill text-primary me-2"></i> Staged Architecture in <code>src/v1/</code>
+      </h2>
+
+      <div class="row g-3">
+        <div class="col-md-6">
+          <div class="feature-card">
+            <h6 class="fw-bold text-success mb-2">
+              <i class="bi bi-shield-check me-1"></i> 1. guards/
+            </h6>
+            <p class="small text-muted mb-0">
+              Validates inputs before any DOM mutation occurs. Separated into <code>container/</code> (validates first input) and <code>bindings/</code> (validates second input array).
+            </p>
+          </div>
+        </div>
+
+        <div class="col-md-6">
+          <div class="feature-card">
+            <h6 class="fw-bold text-info mb-2">
+              <i class="bi bi-collection me-1"></i> 2. prepare/
+            </h6>
+            <p class="small text-muted mb-0">
+              Groups bindings by event type into a <code>Map&lt;eventType, bindings[]&gt;</code>, ensuring only a single listener is registered per event type.
+            </p>
+          </div>
+        </div>
+
+        <div class="col-md-6">
+          <div class="feature-card">
+            <h6 class="fw-bold text-primary mb-2">
+              <i class="bi bi-earbuds me-1"></i> 3. listeners/
+            </h6>
+            <p class="small text-muted mb-0">
+              Attaches container event listeners that intercept bubbling browser events and pass them down into the dispatch pipeline.
+            </p>
+          </div>
+        </div>
+
+        <div class="col-md-6">
+          <div class="feature-card">
+            <h6 class="fw-bold text-warning mb-2">
+              <i class="bi bi-lightning-charge me-1"></i> 4. dispatch/
+            </h6>
+            <p class="small text-muted mb-0">
+              Finds the matching target via <code>closest(selector)</code>, resolves start inputs, executes the runner, and emits extracted data to <code>onExtract</code>.
+            </p>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <!-- Section 3: Browser API & Window.ks -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-2">
+        <i class="bi bi-globe2 text-info me-2"></i> Browser Usage via <code>window.ks</code>
+      </h2>
+      <p class="small text-muted mb-3">
+        Include the bundled distribution or ES module, then call <code>bindEvents</code>:
+      </p>
+
+      <pre class="mb-3"><code>&lt;script type="module" src="/docs/dist/v1/min.js"&gt;&lt;/script&gt;
+&lt;script type="module"&gt;
+  const bindings = [
+    {
+      event: "click",
+      selector: ".btn-delete",
+      runner: (target) => ({ id: target.dataset.id }),
+      onExtract: (data) => console.log("Deleted:", data)
+    }
+  ];
+
+  window.ks.domPrimitiveBindings.bindEvents("container-id", bindings);
+&lt;/script&gt;</code></pre>
+    </section>
+
+    <!-- Section 4: Design Rules & Zero Comments -->
+    <section class="card shadow-sm border-0 p-4">
+      <h2 class="h5 fw-bold text-dark mb-3">
+        <i class="bi bi-check2-circle text-success me-2"></i> Code Conventions
+      </h2>
+      <ul class="list-unstyled mb-0 small text-muted">
+        <li class="mb-2"><i class="bi bi-check-lg text-success me-2"></i><strong>Every folder has an <code>index.js</code></strong> file acting as its public gateway.</li>
+        <li class="mb-2"><i class="bi bi-check-lg text-success me-2"></i><strong>Single-function default export</strong> per file (no default export objects).</li>
+        <li class="mb-2"><i class="bi bi-check-lg text-success me-2"></i><strong>Zero comments in code:</strong> Folders and file names tell the story directly.</li>
+        <li><i class="bi bi-check-lg text-success me-2"></i><strong>Independent sibling package:</strong> Focused purely on event delegation without mixing extraction concerns.</li>
+      </ul>
+    </section>
+
+  </main>
+
+  <footer class="text-center text-muted py-4 border-top small">
+    DOM Primitive Bindings · Single Source of Truth: <code>v1</code> · MIT License
+  </footer>
+
+</body>
+
+</html>

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "dom-primitive-bindings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Declarative, instruction-driven DOM delegated event bindings",
+  "type": "module",
+  "license": "MIT",
+  "author": "KeshavSoft",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keshavsoft/dom-primitive-bindings.git"
+  },
+  "bugs": {
+    "url": "https://github.com/keshavsoft/dom-primitive-bindings/issues"
+  },
+  "homepage": "https://github.com/keshavsoft/dom-primitive-bindings#readme",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/index.js",
+    "src/v1",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "vite": "^6.4.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export * from "./v1/index.js";
+export { default } from "./v1/index.js";
+

package/src/v1/dispatch/executeBinding.js

@@ -0,0 +1,21 @@
+import getStartInput from "./getStartInput.js";
+import getClientData from "./getClientData.js";
+
+const executeBinding = ({ binding, event, matchElement }) => {
+  const startInput = getStartInput(binding, event, matchElement);
+  const clientData = getClientData(binding, event, matchElement);
+  const runner = binding.runner;
+
+  const result = typeof runner === "function"
+    ? runner(startInput, binding.instructions, clientData)
+    : startInput;
+
+  if (result !== null && result !== undefined && typeof binding.onExtract === "function") {
+    binding.onExtract(result, event, matchElement);
+  }
+
+  return result;
+};
+
+export default executeBinding;
+

package/src/v1/dispatch/getClientData.js

@@ -0,0 +1,8 @@
+const getClientData = (binding, event, matchElement) => ({
+  ...binding.clientData,
+  event,
+  targetElement: matchElement
+});
+
+export default getClientData;
+

package/src/v1/dispatch/getStartInput.js

@@ -0,0 +1,10 @@
+const getStartInput = (binding, event, matchElement) => {
+  if (binding.root === "event" || event?.type?.startsWith("key")) {
+    return event;
+  }
+
+  return matchElement;
+};
+
+export default getStartInput;
+

package/src/v1/dispatch/index.js

@@ -0,0 +1,15 @@
+import executeBinding from "./executeBinding.js";
+
+const dispatchEvent = ({ bindings, event, container }) => {
+  for (const binding of bindings) {
+    const matchElement = event.target?.closest?.(binding.selector);
+    if (!matchElement || !container.contains(matchElement)) {
+      continue;
+    }
+
+    executeBinding({ binding, event, matchElement });
+  }
+};
+
+export default dispatchEvent;
+

package/src/v1/guards/bindings/index.js

@@ -0,0 +1,11 @@
+import validateArray from "./validateArray.js";
+
+const checkBindings = (bindings) => {
+  const valid = validateArray(bindings);
+  if (valid.length === 0) return null;
+
+  return valid;
+};
+
+export default checkBindings;
+

package/src/v1/guards/bindings/validateArray.js

@@ -0,0 +1,10 @@
+const validateArray = (bindings) => {
+  if (!Array.isArray(bindings)) return [];
+
+  return bindings.filter((binding) => (
+    binding && typeof binding === "object" && typeof binding.event === "string" && typeof binding.selector === "string"
+  ));
+};
+
+export default validateArray;
+

package/src/v1/guards/container/index.js

@@ -0,0 +1,13 @@
+import resolveElement from "./resolveElement.js";
+
+const checkContainer = (containerOrId) => {
+  if (!containerOrId) return null;
+
+  const element = resolveElement(containerOrId);
+  if (!element) return null;
+
+  return element;
+};
+
+export default checkContainer;
+

package/src/v1/guards/container/resolveElement.js

@@ -0,0 +1,14 @@
+const resolveElement = (containerOrId) => {
+  if (typeof containerOrId === "string") {
+    return document.getElementById(containerOrId) || document.querySelector(containerOrId);
+  }
+
+  if (containerOrId && typeof containerOrId === "object" && "addEventListener" in containerOrId) {
+    return containerOrId;
+  }
+
+  return null;
+};
+
+export default resolveElement;
+

package/src/v1/guards/index.js

@@ -0,0 +1,15 @@
+import checkContainer from "./container/index.js";
+import checkBindings from "./bindings/index.js";
+
+const runGuards = (containerOrId, bindings) => {
+  const container = checkContainer(containerOrId);
+  if (!container) return null;
+
+  const validBindings = checkBindings(bindings);
+  if (!validBindings) return null;
+
+  return { container, bindings: validBindings };
+};
+
+export default runGuards;
+

package/src/v1/index.js

@@ -0,0 +1,22 @@
+import registerGlobal from "./register/index.js";
+import runGuards from "./guards/index.js";
+import prepareBindings from "./prepare/index.js";
+import attachListeners from "./listeners/index.js";
+
+const bindEvents = (containerOrId, bindings = []) => {
+  const guarded = runGuards(containerOrId, bindings);
+  if (!guarded) return null;
+
+  const { container, bindings: validBindings } = guarded;
+  const eventGroups = prepareBindings(validBindings);
+
+  attachListeners(container, eventGroups);
+
+  return container;
+};
+
+export { bindEvents };
+export default bindEvents;
+
+registerGlobal(bindEvents);
+

package/src/v1/listeners/attachListener.js

@@ -0,0 +1,10 @@
+import dispatchEvent from "../dispatch/index.js";
+
+const attachListener = (container, eventType, bindings) => {
+  container.addEventListener(eventType, (event) => {
+    dispatchEvent({ bindings, event, container });
+  });
+};
+
+export default attachListener;
+

package/src/v1/listeners/index.js

@@ -0,0 +1,12 @@
+import attachListener from "./attachListener.js";
+
+const attachListeners = (container, eventGroups) => {
+  for (const [eventType, bindings] of eventGroups.entries()) {
+    attachListener(container, eventType, bindings);
+  }
+
+  return container;
+};
+
+export default attachListeners;
+

package/src/v1/prepare/groupBindings.js

@@ -0,0 +1,14 @@
+const groupBindings = (bindings) => {
+  const groups = new Map();
+
+  for (const binding of bindings) {
+    const list = groups.get(binding.event) ?? [];
+    list.push(binding);
+    groups.set(binding.event, list);
+  }
+
+  return groups;
+};
+
+export default groupBindings;
+

package/src/v1/prepare/index.js

@@ -0,0 +1,8 @@
+import groupBindings from "./groupBindings.js";
+
+const prepareBindings = (bindings) => {
+  return groupBindings(bindings);
+};
+
+export default prepareBindings;
+

package/src/v1/register/index.js

@@ -0,0 +1,17 @@
+import meta from "./meta.js";
+
+const registerGlobal = (bindEvents, metadata = meta) => {
+  if (!bindEvents || typeof globalThis === "undefined") return;
+
+  globalThis.ks ??= {};
+
+  globalThis.ks.domPrimitiveBindings = {
+    meta: metadata,
+    bindEvents
+  };
+
+  return globalThis.ks.domPrimitiveBindings;
+};
+
+export default registerGlobal;
+

package/src/v1/register/meta.js

@@ -0,0 +1,7 @@
+export const meta = {
+  name: "dom-primitive-bindings",
+  version: "1.0.0"
+};
+
+export default meta;
+