npm - wick-dom-observer - Versions diffs - 1.0.0 - Mend

wick-dom-observer 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/.github/workflows/main.yml +12 -0
package/LICENSE +21 -0
package/README.md +530 -0
package/assets/log-observed-dissapear.png +0 -0
package/assets/overview.png +0 -0
package/assets/spinner.png +0 -0
package/assets/timelines.png +0 -0
package/assets/toast.png +0 -0
package/cypress/e2e/modalTableDemo.cy.js +115 -0
package/cypress/e2e/spinnerAndToast.cy.js +313 -0
package/cypress/public/demo.html +847 -0
package/cypress/public/modal-table-demo.html +454 -0
package/cypress/support/commands.js +25 -0
package/cypress/support/e2e.js +20 -0
package/cypress.config.js +13 -0
package/package.json +33 -0
package/src/index.d.ts +144 -0
package/src/index.js +2 -0
package/src/utils.js +509 -0
package/src/watcher.js +178 -0

package/cypress/public/modal-table-demo.html ADDED Viewed

@@ -0,0 +1,454 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Modal + Loading Table Demo</title>
+  <style>
+    :root {
+      --bg-a: #0f172a;
+      --bg-b: #111827;
+      --card: rgba(15, 23, 42, 0.86);
+      --line: rgba(148, 163, 184, 0.24);
+      --text: #e2e8f0;
+      --muted: #94a3b8;
+      --primary-a: #0ea5e9;
+      --primary-b: #6366f1;
+      --success-a: #059669;
+      --success-b: #16a34a;
+      --shadow: 0 14px 40px rgba(2, 6, 23, 0.55);
+    }
+    * {
+      box-sizing: border-box;
+    }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font-family: Inter, Segoe UI, Roboto, Arial, sans-serif;
+      color: var(--text);
+      background:
+        radial-gradient(circle at 15% 10%, rgba(14, 165, 233, 0.16), transparent 35%),
+        radial-gradient(circle at 85% 5%, rgba(99, 102, 241, 0.18), transparent 40%),
+        linear-gradient(170deg, var(--bg-a), var(--bg-b));
+      display: grid;
+      place-items: center;
+      padding: 24px;
+    }
+    .app {
+      width: min(1080px, 100%);
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      box-shadow: var(--shadow);
+      backdrop-filter: blur(6px);
+      overflow: hidden;
+    }
+    .header {
+      padding: 20px 24px 14px;
+      border-bottom: 1px solid var(--line);
+      background: linear-gradient(180deg, rgba(99, 102, 241, 0.12), transparent);
+    }
+    .title {
+      margin: 0;
+      font-size: 1.26rem;
+      font-weight: 750;
+      letter-spacing: 0.2px;
+    }
+    .subtitle {
+      margin: 8px 0 0;
+      color: var(--muted);
+      font-size: 0.94rem;
+    }
+    .content {
+      padding: 22px 24px 24px;
+      display: grid;
+      gap: 16px;
+    }
+    .toolbar {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+      flex-wrap: wrap;
+    }
+    .cta {
+      border: 1px solid transparent;
+      border-radius: 12px;
+      font-size: 0.95rem;
+      font-weight: 700;
+      color: #eff6ff;
+      padding: 11px 16px;
+      cursor: pointer;
+      background: linear-gradient(135deg, var(--primary-a), var(--primary-b));
+      box-shadow: 0 10px 24px rgba(59, 130, 246, 0.35);
+      transition: transform 140ms ease, box-shadow 140ms ease, opacity 140ms ease;
+    }
+    .cta:hover {
+      transform: translateY(-1px);
+      box-shadow: 0 13px 28px rgba(59, 130, 246, 0.42);
+    }
+    .cta:disabled {
+      opacity: 0.72;
+      cursor: default;
+      transform: none;
+      box-shadow: 0 8px 16px rgba(59, 130, 246, 0.2);
+    }
+    .status {
+      color: var(--muted);
+      font-size: 0.9rem;
+      margin: 0;
+    }
+    .loading-row {
+      min-height: 44px;
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+    .spinner-image {
+      width: 36px;
+      height: 36px;
+      border-radius: 999px;
+      border: 4px solid rgba(148, 163, 184, 0.28);
+      border-top-color: #38bdf8;
+      border-right-color: #6366f1;
+      animation: spin 760ms linear infinite;
+      filter: drop-shadow(0 4px 10px rgba(56, 189, 248, 0.25));
+    }
+    .loading-label {
+      margin: 0;
+      font-size: 0.95rem;
+      color: #cbd5e1;
+    }
+    .table-wrap {
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      overflow: hidden;
+      background: rgba(2, 6, 23, 0.38);
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+    }
+    thead th {
+      text-align: left;
+      font-size: 0.84rem;
+      letter-spacing: 0.4px;
+      color: #cbd5e1;
+      padding: 12px 14px;
+      background: rgba(30, 41, 59, 0.84);
+      border-bottom: 1px solid var(--line);
+    }
+    tbody td {
+      padding: 11px 14px;
+      border-bottom: 1px solid rgba(148, 163, 184, 0.14);
+      font-size: 0.91rem;
+      color: #e5e7eb;
+    }
+    tbody tr:nth-child(even) {
+      background: rgba(30, 41, 59, 0.28);
+    }
+    tbody tr:hover {
+      background: rgba(56, 189, 248, 0.12);
+    }
+    .hidden {
+      display: none;
+    }
+    /* Modal */
+    .overlay {
+      position: fixed;
+      inset: 0;
+      background: rgba(2, 6, 23, 0.66);
+      display: grid;
+      place-items: center;
+      z-index: 1000;
+      padding: 20px;
+    }
+    .overlay.hidden {
+      display: none;
+    }
+    .modal {
+      width: min(560px, 100%);
+      border-radius: 18px;
+      border: 1px solid var(--line);
+      background:
+        linear-gradient(160deg, rgba(15, 23, 42, 0.98), rgba(30, 41, 59, 0.98));
+      box-shadow: 0 20px 48px rgba(2, 6, 23, 0.62);
+      overflow: hidden;
+      animation: riseIn 180ms ease-out;
+    }
+    .modal-head {
+      padding: 16px 18px 12px;
+      border-bottom: 1px solid var(--line);
+      background: linear-gradient(180deg, rgba(14, 165, 233, 0.14), transparent);
+    }
+    .modal-title {
+      margin: 0;
+      font-size: 1.05rem;
+      font-weight: 750;
+      color: #e0f2fe;
+    }
+    .modal-body {
+      padding: 16px 18px;
+      color: #cbd5e1;
+      line-height: 1.52;
+      font-size: 0.94rem;
+    }
+    .modal-list {
+      margin: 10px 0 0;
+      padding-left: 18px;
+    }
+    .modal-actions {
+      padding: 0 18px 18px;
+      display: flex;
+      justify-content: flex-end;
+    }
+    .close-modal {
+      border: 1px solid transparent;
+      border-radius: 10px;
+      padding: 10px 14px;
+      font-weight: 700;
+      color: #ecfdf5;
+      background: linear-gradient(135deg, var(--success-a), var(--success-b));
+      cursor: pointer;
+      box-shadow: 0 8px 18px rgba(22, 163, 74, 0.35);
+    }
+    /* Keep ad-overlay modal behavior, but style like a top banner. */
+    #adOverlay {
+      place-items: start center;
+      padding: 14px 16px 24px;
+      background: rgba(2, 6, 23, 0.6);
+    }
+    #adOverlay .modal {
+      width: min(1040px, calc(100% - 10px));
+      border-radius: 14px;
+      border: 1px solid rgba(250, 204, 21, 0.68);
+      background:
+        repeating-linear-gradient(-45deg,
+          rgba(245, 158, 11, 0.16) 0 14px,
+          rgba(234, 88, 12, 0.16) 14px 28px),
+        linear-gradient(140deg, rgba(30, 41, 59, 0.98), rgba(15, 23, 42, 0.98));
+      box-shadow: 0 16px 36px rgba(2, 6, 23, 0.66);
+      animation: bannerDrop 220ms ease-out;
+    }
+    #adOverlay .modal-head {
+      padding: 12px 16px 10px;
+      background: linear-gradient(180deg, rgba(250, 204, 21, 0.2), transparent);
+      border-bottom: 1px solid rgba(250, 204, 21, 0.32);
+    }
+    #adOverlay .modal-title {
+      color: #fef3c7;
+      font-size: 1.1rem;
+      letter-spacing: 0.25px;
+    }
+    #adOverlay .modal-body {
+      padding: 12px 16px;
+      color: #fef9c3;
+    }
+    #adOverlay .modal-actions {
+      padding: 0 16px 14px;
+    }
+    @keyframes spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+    @keyframes riseIn {
+      from {
+        opacity: 0;
+        transform: translateY(14px) scale(0.98);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+      }
+    }
+    @keyframes bannerDrop {
+      from {
+        opacity: 0;
+        transform: translateY(-18px);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0);
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="app">
+    <header class="header">
+      <h1 class="title">Campaign Data Loader</h1>
+      <p class="subtitle">
+        Click the button to load data and validate the loading flow.
+      </p>
+    </header>
+    <section class="content">
+      <div class="toolbar">
+        <button id="loadDataBtn" data-cy="load-data-btn" class="cta" type="button">Load Campaign Data Spinner</button>
+        <p id="statusText" class="status">Ready to load data.</p>
+      </div>
+      <div id="loadingRow" data-cy="loading-row" class="loading-row hidden" aria-live="polite">
+        <div class="spinner-image" data-cy="service-spinner"></div>
+        <p class="loading-label">Fetching latest campaign analytics...</p>
+      </div>
+      <div id="tableWrap" data-cy="table-wrap" class="table-wrap hidden">
+        <table>
+          <thead>
+            <tr>
+              <th>Campaign ID</th>
+              <th>Channel</th>
+              <th>Region</th>
+              <th>Daily Budget</th>
+              <th>Status</th>
+            </tr>
+          </thead>
+          <tbody id="resultRows" data-cy="result-rows"></tbody>
+        </table>
+      </div>
+    </section>
+  </div>
+  <div id="adOverlay" data-cy="ad-overlay" class="overlay hidden" role="dialog" aria-modal="true"
+    aria-labelledby="adTitle">
+    <div class="modal">
+      <div class="modal-head">
+        <h2 id="adTitle" class="modal-title">Limited Offer: AI Insights Upgrade</h2>
+      </div>
+      <div class="modal-body">
+        Unlock deeper performance insights with premium analytics features:
+        <ul class="modal-list">
+          <li>Real-time anomaly detection for active campaigns.</li>
+          <li>Predictive recommendations for budget allocation.</li>
+          <li>Automated daily summaries delivered to your inbox.</li>
+        </ul>
+      </div>
+      <div class="modal-actions">
+        <button id="closeAdBtn" data-cy="close-ad-btn" class="close-modal" type="button">Close and Continue</button>
+      </div>
+    </div>
+  </div>
+  <script>
+    (function () {
+      var loadDataBtn = document.getElementById('loadDataBtn')
+      var statusText = document.getElementById('statusText')
+      var loadingRow = document.getElementById('loadingRow')
+      var tableWrap = document.getElementById('tableWrap')
+      var resultRows = document.getElementById('resultRows')
+      var adOverlay = document.getElementById('adOverlay')
+      var closeAdBtn = document.getElementById('closeAdBtn')
+      function getMockRows() {
+        return [
+          ['CMP-1001', 'Search', 'North', '$1,450', 'Active'],
+          ['CMP-1002', 'Social', 'West', '$980', 'Active'],
+          ['CMP-1003', 'Display', 'South', '$730', 'Paused'],
+          ['CMP-1004', 'Email', 'East', '$420', 'Active'],
+          ['CMP-1005', 'Search', 'Global', '$1,960', 'Active'],
+          ['CMP-1006', 'Social', 'North', '$840', 'Draft'],
+          ['CMP-1007', 'Display', 'Central', '$610', 'Active'],
+          ['CMP-1008', 'Email', 'West', '$390', 'Paused'],
+          ['CMP-1009', 'Search', 'East', '$1,120', 'Active'],
+          ['CMP-1010', 'Social', 'South', '$890', 'Active'],
+        ]
+      }
+      function renderRows(rows) {
+        resultRows.innerHTML = ''
+        rows.forEach(function (cells) {
+          var tr = document.createElement('tr')
+          cells.forEach(function (value) {
+            var td = document.createElement('td')
+            td.textContent = value
+            tr.appendChild(td)
+          })
+          resultRows.appendChild(tr)
+        })
+      }
+      function startLoad() {
+        loadDataBtn.disabled = true
+        tableWrap.classList.add('hidden')
+        loadingRow.classList.add('hidden')
+        statusText.textContent = 'Calling service... preparing request.'
+        var showSpinnerAfterMs = 500 + Math.floor(Math.random() * 1501) // 500-2000
+        var spinnerVisibleForMs = 500 + Math.floor(Math.random() * 2501) // 500-3000
+        setTimeout(function () {
+          loadingRow.classList.remove('hidden')
+          statusText.textContent = 'Fetching latest campaign analytics...'
+          setTimeout(function () {
+            renderRows(getMockRows())
+            loadingRow.classList.add('hidden')
+            tableWrap.classList.remove('hidden')
+            statusText.textContent = 'Data loaded successfully.'
+            loadDataBtn.disabled = false
+          }, spinnerVisibleForMs)
+        }, showSpinnerAfterMs)
+      }
+      loadDataBtn.addEventListener('click', function () {
+        startLoad()
+      })
+      closeAdBtn.addEventListener('click', function () {
+        adOverlay.classList.add('hidden')
+      })
+      // 50% chance to show the advertisement modal at load.
+      if (Math.random() < 0.5) {
+        adOverlay.classList.remove('hidden')
+      }
+    })()
+  </script>
+</body>
+</html>

package/cypress/support/commands.js ADDED Viewed

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })

package/cypress/support/e2e.js ADDED Viewed

@@ -0,0 +1,20 @@
+// ***********************************************************
+// This example support/e2e.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+// Load the wick-dom-observer plugin (use package name when published)
+import '../../src/index.js'
+// Import commands.js using ES2015 syntax:
+import './commands'

package/cypress.config.js ADDED Viewed

@@ -0,0 +1,13 @@
+const { defineConfig } = require("cypress");
+module.exports = defineConfig({
+  allowCypressEnv: false,
+  watchForFileChanges: false,
+  e2e: {
+    baseUrl: 'http://localhost:3030',
+    setupNodeEvents(on, config) {
+      // implement node event listeners here
+    },
+  },
+});

package/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "wick-dom-observer",
+  "version": "1.0.0",
+  "description": "A Cypress plugin that watches DOM changes after clicks to detect fast loading spinners and async UI transitions. It improves test reliability by waiting for real visual completion instead of fixed delays or intercepts.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "keywords": [
+    "cypress",
+    "spinner",
+    "loading",
+    "custom-command",
+    "testing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "demo:serve": "serve cypress/public -p 3030",
+    "cy:open": "start-server-and-test serve 3030 cypress:open",
+    "cy:run": "start-server-and-test serve 3030 cypress:run",
+    "cypress:open": "cypress open",
+    "cypress:run": "cypress run",
+    "serve": "serve cypress/public -p 3030"
+  },
+  "devDependencies": {
+    "serve": "^14.2.4",
+    "start-server-and-test": "^2.0.3"
+  },
+  "peerDependencies": {
+    "cypress": "^15.11.0"
+  }
+}

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,144 @@
+/// <reference types="cypress" />
+declare global {
+    namespace Cypress {
+        type ClickSpinnerAppearMode = 'optional' | 'required'
+        interface ClickSpinnerConfig {
+            selector: string
+            assert: ($el: JQuery<HTMLElement>) => void
+            action?: ($el: JQuery<HTMLElement>) => void
+            timeout?: number
+            pollingInterval?: number
+            appear?: ClickSpinnerAppearMode
+            disappear?: boolean
+            mustLast?: number
+        }
+        interface Chainable {
+            /**
+             * Cypress custom command that clicks an element and watches for a spinner in the DOM.
+             * It is designed for very fast loading indicators that may appear and disappear between
+             * normal Cypress assertions.
+             *
+             * The command supports all common `.click()` signatures after the required `config` object:
+             * - `clickAndWatchForElement(config)`
+             * - `clickAndWatchForElement(config, options)`
+             * - `clickAndWatchForElement(config, position)`
+             * - `clickAndWatchForElement(config, position, options)`
+             * - `clickAndWatchForElement(config, x, y)`
+             * - `clickAndWatchForElement(config, x, y, options)`
+             *
+             * @param {Cypress.ClickSpinnerConfig} config - Spinner behavior configuration.
+             *   - {string} selector: CSS selector used to find the spinner.
+             *   - {Function} assert: Synchronous assertion callback executed when spinner is found.
+             *   - {Function} [action]: Synchronous callback executed after `assert` passes.
+             *   - {number} [timeout]: Max wait time in ms for appear/disappear checks.
+             *   - {number} [pollingInterval]: Polling interval in ms (used for disappear checks).
+             *   - {'optional'|'required'} [appear='optional']:
+             *       - `optional`: spinner may not appear.
+             *       - `required`: command fails if spinner does not appear and satisfy `assert` in time.
+             *   - {boolean} [disappear=false]: If true, also waits for spinner to be removed from DOM.
+             *   - {number} [mustLast]: Minimum time in ms spinner must remain in DOM (when `appear: 'required'`).
+             * @param {Cypress.ClickOptions} [options] - Optional Cypress click options.
+             * @param {Cypress.PositionType} [position] - Optional click position string.
+             * @param {number} [x] - Optional x coordinate for click.
+             * @param {number} [y] - Optional y coordinate for click.
+             * @returns {Cypress.Chainable} Returns the original subject for further chaining.
+             *
+             * @example
+             * // Basic usage
+             * cy.get('[data-cy="save-button"]').clickAndWatchForElement({
+             *   selector: '.loading-spinner',
+             *   assert: ($el) => {
+             *     expect($el).to.be.visible()
+             *   },
+             * })
+             *
+             * @example
+             * // Require spinner appearance and disappearance
+             * cy.get('[data-cy="save-button"]').clickAndWatchForElement({
+             *   selector: '.loading-spinner',
+             *   appear: 'required',
+             *   disappear: true,
+             *   timeout: 10000,
+             *   assert: ($el) => {
+             *     expect($el).to.have.class('loading')
+             *   },
+             * })
+             *
+             * @example
+             * // Position + click options
+             * cy.get('[data-cy="save-button"]').clickAndWatchForElement(
+             *   {
+             *     selector: '.loading-spinner',
+             *     assert: ($el) => {
+             *       expect($el).to.be.visible()
+             *     },
+             *   },
+             *   'topRight',
+             *   { force: true }
+             * )
+             *
+             * @example
+             * // Coordinates + mustLast
+             * cy.get('canvas').clickAndWatchForElement(
+             *   {
+             *     selector: '.spinner',
+             *     appear: 'required',
+             *     mustLast: 100,
+             *     assert: ($el) => {
+             *       expect($el.text()).to.eq('Loading')
+             *     },
+             *   },
+             *   20,
+             *   40,
+             *   { force: true }
+             * )
+             */
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig
+            ): Chainable
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig,
+                options: Partial<ClickOptions>
+            ): Chainable
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig,
+                position: PositionType
+            ): Chainable
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig,
+                position: PositionType,
+                options: Partial<ClickOptions>
+            ): Chainable
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig,
+                x: number,
+                y: number
+            ): Chainable
+            clickAndWatchForElement(
+                config: ClickSpinnerConfig,
+                x: number,
+                y: number,
+                options: Partial<ClickOptions>
+            ): Chainable
+            /**
+             * Watches for an element to appear/disappear using the same config behavior as
+             * `clickAndWatchForElement`, but without performing any click action.
+             *
+             * Useful for observing elements that may appear automatically (e.g. on page load).
+             *
+             * @param {Cypress.ClickSpinnerConfig} config - Element watch configuration.
+             * @returns {Cypress.Chainable} Chainable that resolves when watch flow completes.
+             */
+            watchForElement(
+                config: ClickSpinnerConfig
+            ): Chainable
+        }
+    }
+}
+export {}

package/src/index.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import './watcher'
2	+