dom-primitive-bindings 1.0.0 → 1.3.1

package/docs/stories/03-the-staged-pipeline.html

@@ -0,0 +1,162 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Chapter 3: The Staged Pipeline — DOM Primitive Bindings</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.65;
+    }
+    .story-hero {
+      background: linear-gradient(135deg, #065f46 0%, #047857 100%);
+      color: #fff;
+      padding: 40px 0;
+    }
+    pre {
+      background-color: #0f172a;
+      color: #e2e8f0;
+      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;
+    }
+    .stage-card {
+      border: 1px solid #e2e8f0;
+      background: #fff;
+      border-radius: 8px;
+      padding: 20px;
+    }
+  </style>
+</head>
+
+<body>
+
+  <header class="story-hero shadow-sm mb-4">
+    <div class="container">
+      <div class="d-flex justify-content-between align-items-center flex-wrap gap-2">
+        <div>
+          <span class="badge bg-purple text-white mb-2" style="background:#7c3aed;">Chapter 3 of 4</span>
+          <h1 class="h3 fw-bold mb-1">The Staged Pipeline Architecture</h1>
+          <p class="text-white small mb-0">How src/v3 turns complex delegation into 4 crystal-clear decoupled stages.</p>
+        </div>
+        <a href="../index.html" class="btn btn-outline-light btn-sm">
+          <i class="bi bi-arrow-left me-1"></i> Story Index
+        </a>
+      </div>
+    </div>
+  </header>
+
+  <main class="container pb-5" style="max-width: 900px;">
+
+    <!-- Overview -->
+    <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-2 text-primary me-2"></i> Inside the <code>src/v3/</code> Pipeline
+      </h2>
+      <p>
+        Rather than writing a monolithic event listener, <code>dom-primitive-bindings</code> breaks the work into 4 decoupled stages where every folder contains an <code>index.js</code> and exports a single function:
+      </p>
+
+      <div class="row g-3">
+
+        <!-- Stage 1 -->
+        <div class="col-md-6">
+          <div class="stage-card h-100">
+            <span class="badge bg-success mb-2">Stage 1</span>
+            <h5 class="h6 fw-bold text-dark mb-1">guards/</h5>
+            <p class="small text-muted mb-0">
+              Validates and resolves inputs before touching the DOM:
+              <br>• <code>container/</code>: Resolves container ID or DOM node.
+              <br>• <code>bindings/</code>: Validates that bindings is a valid array of items with <code>event</code> and <code>selector</code>.
+            </p>
+          </div>
+        </div>
+
+        <!-- Stage 2 -->
+        <div class="col-md-6">
+          <div class="stage-card h-100">
+            <span class="badge bg-info text-dark mb-2">Stage 2</span>
+            <h5 class="h6 fw-bold text-dark mb-1">prepare/</h5>
+            <p class="small text-muted mb-0">
+              Groups all bindings by event type into a <code>Map&lt;eventType, bindings[]&gt;</code>.
+              If you have 10 click bindings, it ensures only <strong>one</strong> click listener is attached to the container.
+            </p>
+          </div>
+        </div>
+
+        <!-- Stage 3 -->
+        <div class="col-md-6">
+          <div class="stage-card h-100">
+            <span class="badge bg-primary mb-2">Stage 3</span>
+            <h5 class="h6 fw-bold text-dark mb-1">listeners/</h5>
+            <p class="small text-muted mb-0">
+              Attaches the container event listeners. Each listener intercepts the native bubbling event and invokes the dispatch pipeline.
+            </p>
+          </div>
+        </div>
+
+        <!-- Stage 4 -->
+        <div class="col-md-6">
+          <div class="stage-card h-100">
+            <span class="badge bg-warning text-dark mb-2">Stage 4</span>
+            <h5 class="h6 fw-bold text-dark mb-1">dispatch/</h5>
+            <p class="small text-muted mb-0">
+              Matches target elements via <code>event.target.closest(binding.selector)</code>, resolves inputs (keyboard vs click element), and passes <code>{ event, matchElement }</code> to the runner.
+            </p>
+          </div>
+        </div>
+
+      </div>
+    </section>
+
+    <!-- Code Blueprint -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-3">
+        <i class="bi bi-code-square text-success me-2"></i> The Orchestrator (<code>src/v3/index.js</code>)
+      </h2>
+      <pre class="mb-0"><code>const bindEvents = (containerOrId, bindings = []) => {
+  // 1. Validate inputs
+  const guarded = runGuards(containerOrId, bindings);
+  if (!guarded) return null;
+
+  // 2. Group bindings by event type
+  const { container, bindings: validBindings } = guarded;
+  const eventGroups = prepareBindings(validBindings);
+
+  // 3. Attach container listeners (delegating to dispatch)
+  attachListeners(container, eventGroups);
+
+  return container;
+};</code></pre>
+    </section>
+
+    <!-- Navigation -->
+    <div class="d-flex justify-content-between align-items-center mt-4">
+      <a href="./02-the-delegation-epiphany.html" class="btn btn-outline-secondary">
+        <i class="bi bi-arrow-left me-1"></i> Chapter 2: The Epiphany
+      </a>
+      <a href="./04-declarative-json-bindings.html" class="btn btn-success">
+        Next: Chapter 4 — Declarative JSON Bindings <i class="bi bi-arrow-right ms-1"></i>
+      </a>
+    </div>
+
+  </main>
+
+</body>
+
+</html>
+

package/docs/stories/04-declarative-json-bindings.html

@@ -0,0 +1,159 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Chapter 4: The Joy of Declarative JSON — DOM Primitive Bindings</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.65;
+    }
+    .story-hero {
+      background: linear-gradient(135deg, #065f46 0%, #047857 100%);
+      color: #fff;
+      padding: 40px 0;
+    }
+    pre {
+      background-color: #0f172a;
+      color: #e2e8f0;
+      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;
+    }
+    .demo-box {
+      background: #ffffff;
+      border: 1px solid #cbd5e1;
+      border-radius: 8px;
+      padding: 20px;
+    }
+  </style>
+</head>
+
+<body>
+
+  <header class="story-hero shadow-sm mb-4">
+    <div class="container">
+      <div class="d-flex justify-content-between align-items-center flex-wrap gap-2">
+        <div>
+          <span class="badge bg-success mb-2">Chapter 4 of 4</span>
+          <h1 class="h3 fw-bold mb-1">The Joy of Declarative JSON Bindings</h1>
+          <p class="text-white small mb-0">Moving from imperative JavaScript arrays to clean, serializable bindings.json specifications.</p>
+        </div>
+        <a href="../index.html" class="btn btn-outline-light btn-sm">
+          <i class="bi bi-arrow-left me-1"></i> Story Index
+        </a>
+      </div>
+    </div>
+  </header>
+
+  <main class="container pb-5" style="max-width: 900px;">
+
+    <!-- Part 1: Why JSON? -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-3">
+        <i class="bi bi-filetype-json text-primary me-2"></i> 1. The Declarative Transformation (v3)
+      </h2>
+      <p>
+        In <strong>v3</strong>, event bindings are completely decoupled from JavaScript code. Instead of writing imperative JS handlers, your events are declared in a clean, serializable <code>bindings.json</code> file:
+      </p>
+
+      <pre><code>// bindings.json
+[
+  {
+    "event": "click",
+    "selector": ".btn-show"
+  },
+  {
+    "event": "keydown",
+    "selector": "input[type='search']"
+  }
+]</code></pre>
+
+      <p class="mb-0">
+        Your application simply imports this JSON and feeds it to <code>bindEvents</code>.
+      </p>
+    </section>
+
+    <!-- Part 2: Interactive Live Demo -->
+    <section class="card shadow-sm border-0 p-4 mb-4">
+      <h2 class="h5 fw-bold text-dark mb-2">
+        <i class="bi bi-play-circle text-success me-2"></i> 2. Live Interactive Demo
+      </h2>
+      <p class="small text-muted mb-3">
+        This demo is running live in your browser using <code>dom-primitive-bindings (v3)</code>:
+      </p>
+
+      <div class="demo-box mb-3" id="live-demo-container">
+        <div class="input-group input-group-sm mb-3" style="max-width: 400px;">
+          <input type="search" class="form-control" placeholder="Type here and press Enter...">
+          <button class="btn btn-primary" type="button">Search</button>
+        </div>
+
+        <div class="d-flex gap-2">
+          <button class="btn btn-outline-primary btn-sm btn-show" data-id="101">Show Row #101</button>
+          <button class="btn btn-outline-success btn-sm btn-show" data-id="102">Show Row #102</button>
+          <button class="btn btn-outline-secondary btn-sm btn-show" data-id="103">Show Row #103</button>
+        </div>
+      </div>
+
+      <div class="bg-dark text-info p-3 rounded font-monospace small" id="live-log">
+        // Click any button or press Enter in the search input to observe the event captured from bindings.json...
+      </div>
+    </section>
+
+    <!-- Navigation -->
+    <div class="d-flex justify-content-between align-items-center mt-4">
+      <a href="./03-the-staged-pipeline.html" class="btn btn-outline-secondary">
+        <i class="bi bi-arrow-left me-1"></i> Chapter 3: The Pipeline
+      </a>
+      <a href="../index.html" class="btn btn-success">
+        <i class="bi bi-house me-1"></i> Return to Documentation Hub
+      </a>
+    </div>
+
+  </main>
+
+  <script type="module" src="../../dist/v3/min.js"></script>
+  <script type="module">
+    const logBox = document.getElementById("live-log");
+
+    const jsonBindings = [
+      { event: "click", selector: ".btn-show" },
+      { event: "keydown", selector: "input[type='search']" }
+    ];
+
+    const activeBindings = jsonBindings.map((binding) => ({
+      ...binding,
+      onExtract: (result, event, matchElement) => {
+        const payload = {
+          event: event.type,
+          selector: binding.selector,
+          targetTag: matchElement.tagName,
+          key: event.key,
+          id: matchElement.dataset.id
+        };
+        logBox.innerHTML = `Event Dispatched: <span class="text-warning">${JSON.stringify(payload)}</span>`;
+      }
+    }));
+
+    window.ks.domPrimitiveBindings?.bindEvents("live-demo-container", activeBindings);
+  </script>
+
+</body>
+
+</html>
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dom-primitive-bindings",
-  "version": "1.0.0",
+  "version": "1.3.1",
   "description": "Declarative, instruction-driven DOM delegated event bindings",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   },
   "files": [
     "src/index.js",
-    "src/v1",
+    "src/v3",
     "docs",
     "README.md",
     "LICENSE"
@@ -33,4 +33,4 @@
   "devDependencies": {
     "vite": "^6.4.1"
   }
-}
+}

package/src/index.js

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

package/src/{v1 → v3}/register/index.js

@@ -10,8 +10,9 @@ const registerGlobal = (bindEvents, metadata = meta) => {
     bindEvents
   };
 
+  globalThis.ks.bindEvents ??= bindEvents;
+
   return globalThis.ks.domPrimitiveBindings;
 };
 
 export default registerGlobal;
-

package/src/{v1 → v3}/register/meta.js

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