spyne 0.24.0 → 0.26.0

package/src/spyne/utils/spyne-warn.js

@@ -0,0 +1,26 @@
+/**
+ * Central outlet for SpyneJS developer-hint warnings (invalid selectors,
+ * sanitized attributes, policy removals, deprecations).
+ *
+ * Warnings are suppressed when window.SPYNE_SUPPRESS_WARNINGS is true —
+ * primarily for test runs, where expected-failure cases would otherwise
+ * flood the reporter. The flag lives on window (not module state) so it
+ * spans separately bundled test files.
+ *
+ * Security-posture warnings (e.g. config.disableSanitize) do NOT route
+ * through here and are always printed.
+ */
+const spyneWarn = (...args) => {
+  const suppressed = typeof window !== 'undefined' && window.SPYNE_SUPPRESS_WARNINGS === true
+  if (suppressed !== true) {
+    console.warn(...args)
+  }
+}
+
+const setSpyneWarningsDisabled = (bool = true) => {
+  if (typeof window !== 'undefined') {
+    window.SPYNE_SUPPRESS_WARNINGS = bool === true
+  }
+}
+
+export { spyneWarn, setSpyneWarningsDisabled }

package/src/spyne/views/dom-element-template.js

@@ -36,6 +36,27 @@ export class DomElementTemplate {
     this.isProxyData = data.__cms__isProxy === true
     this.testMode = opts?.testMode
 
+    // CMS lineage pass — construction-time only, and only in authoring mode.
+    // In production (enableCMSProxies false) this costs one boolean read;
+    // nothing here ever runs inside the substitution loops.
+    if (this.isProxyData === false && SpyneAppProperties.enableCMSProxies === true) {
+      const rehydrated = SpyneAppProperties.rehydrateCmsData?.(data)
+      if (rehydrated !== undefined) {
+        // a stripped clone was re-identified — render with the revived proxy
+        data = rehydrated
+        this.isProxyData = true
+      } else if (DomElementTemplate.templateBindsProxiedChild(data, this.template) === true) {
+        // plain wrapper holding proxied values (e.g. a pageData container),
+        // AND this template actually references one of those proxied children
+        // via a dot-path or loop token — only then is CMS wrapping useful.
+        // Flipping on child presence alone put ~40% of all templates through
+        // the wrap→inflate→sanitize→strip pipeline for zero bindings.
+        this.isProxyData = true
+      } else if (SpyneAppProperties.debug === true) {
+        SpyneAppProperties.warnUnproxiedCmsData?.(data, this.template)
+      }
+    }
+
     // Normalize triple-bracket tags to double-bracket.
     //
     // DomElementTemplate treats {{{key}}} as an alias for {{key}} — both
@@ -105,6 +126,57 @@ export class DomElementTemplate {
     return /({{\.\*?}})/.test(str)
   }
 
+  /**
+   * Shallow, one-level scan for CMS-proxied values inside a plain container,
+   * bailing on the first hit. Lets wrappers that hold proxied content (a
+   * pageData object, a filtered array of proxied stories) opt in to CMS
+   * template wrapping even though the wrapper itself is not a proxy.
+   * Only ever called in authoring mode (enableCMSProxies true).
+   */
+  /**
+   * Wrapper detection with a binding test: returns true only when data holds
+   * a proxied child under a key that the template actually references via a
+   * dot-path ({{key.prop}}) or loop ({{#key}} / {{#key.path}}) token. A
+   * template that never reaches into the proxied child gains nothing from
+   * CMS wrapping — its own top-level tokens have no dataId to bind — so
+   * flipping it into proxy mode only pays the wrap/sanitize/strip pipeline.
+   */
+  static templateBindsProxiedChild(data, template) {
+    if (data === null || typeof data !== 'object' || typeof template !== 'string') {
+      return false
+    }
+    if (template.indexOf('{{') === -1) {
+      return false
+    }
+    const keys = Object.keys(data)
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]
+      const val = data[key]
+      if (val !== null && typeof val === 'object' && val.__cms__isProxy === true) {
+        if (template.indexOf(`{{${key}.`) !== -1 ||
+            template.indexOf(`{{#${key}}}`) !== -1 ||
+            template.indexOf(`{{#${key}.`) !== -1) {
+          return true
+        }
+      }
+    }
+    return false
+  }
+
+  static hasProxiedChild(data) {
+    if (data === null || typeof data !== 'object') {
+      return false
+    }
+    const values = Object.values(data)
+    for (let i = 0; i < values.length; i++) {
+      const val = values[i]
+      if (val !== null && typeof val === 'object' && val.__cms__isProxy === true) {
+        return true
+      }
+    }
+    return false
+  }
+
   /**
    * Normalizes triple-bracket tags to double-bracket form.
    *
@@ -219,8 +291,26 @@ export class DomElementTemplate {
   /**
    * @desc Returns a document fragment generated from the template and any added data.
    */
+  /**
+   * Unwraps <spyne-cms-item> elements whose data-cms-id resolved to an empty
+   * string — tokens that live on a plain wrapper (no __cms__dataId) rather
+   * than on CMS content. Leaves their inner text in place, so the rendered
+   * DOM matches what a non-CMS render would produce. Only runs in authoring
+   * mode (isProxyData true), one pass over the final HTML string.
+   */
+  static stripInertCmsItems(html) {
+    if (html.indexOf('data-cms-id=""') === -1) {
+      return html
+    }
+    const inertRE = /<spyne-cms-item data-cms-id=""[^>]*>[\s\S]*?<spyne-cms-item-text>([\s\S]*?)<\/spyne-cms-item-text>\s*<\/spyne-cms-item>/g
+    return html.replace(inertRE, '$1')
+  }
+
   renderDocFrag() {
     let html = DomElementTemplate.replaceImgPath(this.finalArr.join(''))
+    if (this.isProxyData === true) {
+      html = DomElementTemplate.stripInertCmsItems(html)
+    }
     if (this.testMode !== true) {
       html = sanitizeHTML(html)
     }
@@ -234,6 +324,9 @@ export class DomElementTemplate {
   renderToString() {
     let html = this.finalArr.join('')
     html = DomElementTemplate.replaceImgPath(html)
+    if (this.isProxyData === true) {
+      html = DomElementTemplate.stripInertCmsItems(html)
+    }
     if (this.testMode !== true) {
       // String(...) unwraps TrustedHTML when strict mode is active,
       // keeping this method's string contract.

package/src/spyne/views/dom-element.js

@@ -1,7 +1,8 @@
 import { baseCoreMixins } from '../utils/mixins/base-core-mixins.js'
+import { spyneWarn } from '../utils/spyne-warn.js'
 import { DomElementTemplate } from './dom-element-template.js'
 import { deepMerge } from '../utils/deep-merge.js'
-import { sanitizeAttribute, applyIframeHardening } from '../utils/sanitize-data.js'
+import { sanitizeAttribute, applyElementHardening } from '../utils/sanitize-data.js'
 import { is, defaultTo, pick, mapObjIndexed, forEachObjIndexed, pipe } from 'ramda'
 
 class DomElement {
@@ -67,7 +68,7 @@ class DomElement {
       if (testMode !== true) {
         const { allowed, value } = sanitizeAttribute(key, val, el.tagName)
         if (allowed !== true) {
-          console.warn(`SPYNE WARNING: The attribute "${key}" was removed during sanitization.`, el)
+          spyneWarn(`SPYNE WARNING: The attribute "${key}" was removed during sanitization.`, el)
           return
         }
         val = value
@@ -78,7 +79,7 @@ class DomElement {
     this.getProp('attrs').forEach(addAttributes)
 
     if (testMode !== true) {
-      applyIframeHardening(el)
+      applyElementHardening(el)
     }
 
     return el

package/src/spyne/views/view-stream-selector.js

@@ -1,4 +1,5 @@
 import { head, compose, reject, split, isEmpty, lte, defaultTo, prop } from 'ramda'
+import { spyneWarn } from '../utils/spyne-warn.js'
 import { SpyneAppProperties } from '../utils/spyne-app-properties.js'
 
 function generateSpyneSelectorId(el) {
@@ -32,7 +33,7 @@ function testSelectors(cxt, sel, verboseBool) {
   const elIsDomElement = compose(lte(0), defaultTo(-1), prop('nodeType'))
 
   if (el !== null && elIsDomElement(el) === false) {
-    console.warn(`Spyne Warning: the el object is not a valid single element, ${el}`)
+    spyneWarn(`Spyne Warning: the el object is not a valid single element, ${el}`)
     return
   }
 
@@ -48,7 +49,7 @@ function testSelectors(cxt, sel, verboseBool) {
 
     const isValidSelectorBool = isValidSelector(sel)
     if (verboseBool === true && isDevMode() === true && isValidSelectorBool === false) {
-      console.warn(`Spyne Warning: the selector, ${sel} does not exist in this el, ${cxt}`)
+      spyneWarn(`Spyne Warning: the selector, ${sel} does not exist in this el, ${cxt}`)
     }
   }
 }
@@ -127,8 +128,6 @@ function ViewStreamSelector(cxt, sel) {
    */
   selector.forEach = (fn) => Array.from(getNodeListArray(cxt, sel)).map(fn)
 
-  selector.getNodeListArray = () => getNodeListArray(cxt, sel)
-
   /**
    *
    * Adds the class to the Element or to the NodeList.
@@ -142,7 +141,7 @@ function ViewStreamSelector(cxt, sel) {
     const arr = getNodeListArray(cxt, sel)
     const addClass = item => item.classList.add(c)
     arr.forEach(addClass)
-    return this
+    return selector
   }
 
   /**
@@ -156,7 +155,7 @@ function ViewStreamSelector(cxt, sel) {
       item.classList.remove(c)
     }
     arr.forEach(removeClass)
-    return this
+    return selector
   }
 
   /**
@@ -181,7 +180,7 @@ function ViewStreamSelector(cxt, sel) {
       classStrArr.forEach(adder)
     }
     arr.forEach(setTheClass)
-    return this
+    return selector
   }
 
   selector.unmount = () => {
@@ -205,23 +204,25 @@ function ViewStreamSelector(cxt, sel) {
       bool ? item.classList.add(c) : item.classList.remove(c)
     }
     arr.forEach(toggleClass)
-    return this
+    return selector
   }
 
   selector.toggle = (c, bool) => {
     selector.toggleClass(c, bool)
-    return this
+    return selector
   }
 
   /**
-   * Attaches html to the Selector's element
+   * Attaches html to the Selector's element (the first match when the
+   * selector matches multiple elements).
    * @param htmlElement
    */
   selector.appendChild = (htmlElement) => {
-    if (selector.el.length !== 0) {
-      selector.el.appendChild(htmlElement)
+    const el = selector.el
+    if (el !== null) {
+      el.appendChild(htmlElement)
     } else {
-      console.warn(`Spyne Warning: The selector, ${sel} does not appear to be valid!`)
+      spyneWarn(`Spyne Warning: The selector, ${sel} does not appear to be valid!`)
     }
 
     return selector.el
@@ -244,7 +245,7 @@ function ViewStreamSelector(cxt, sel) {
       arr.forEach(addClass)
     }
     requestAnimationFrame(delayAddClass)
-    // window.setTimeout(delayAddClass, 1);
+    return selector
   }
 
   /**
@@ -253,19 +254,6 @@ function ViewStreamSelector(cxt, sel) {
    * @param {String|HTMLElement} elSel The selector for the element.
    * @desc Sets the class active HTMLElement from a NodeList.
    */
-  selector.setActiveItem2 = (c, elSel) => {
-    const arr = getNodeListArray(cxt, sel)
-    const currentEl = typeof (elSel) === 'string' ? getElOrList(cxt, elSel) : elSel
-    const toggleBool = item => item.isEqualNode(currentEl) ? item.classList.add(c) : item.classList.remove(c)
-    if (isNodeElement(currentEl) === true) {
-      arr.forEach(toggleBool)
-    } else if (isDevMode() === true) {
-      // console.log("SEL IS ",elSel,c);
-      console.warn(`Spyne Warning: The selector, ${elSel}, does not appear to be a valid item in setActiveItem: ${c}`)
-    }
-    return this
-  }
-
   selector.setActiveItem = (c, elSel) => {
     const arr = getNodeListArray(cxt, sel)
     const currentEl = typeof elSel === 'string'
@@ -280,17 +268,17 @@ function ViewStreamSelector(cxt, sel) {
       if (matchingEl) {
         matchingEl.classList.add(c)
       } else if (isDevMode() === true) {
-        console.warn(
+        spyneWarn(
           `Spyne Warning: The selector, ${elSel}, is valid but does not match any item in setActiveItem: ${c}`
         )
       }
     } else if (isDevMode() === true) {
-      console.warn(
+      spyneWarn(
         `Spyne Warning: The selector, ${elSel}, does not appear to be a valid item in setActiveItem: ${c}`
       )
     }
 
-    return this
+    return selector
   }
 
   /**
@@ -298,10 +286,24 @@ function ViewStreamSelector(cxt, sel) {
    * @function el
    *
    * @desc
-   * getter for the selector
+   * getter that always resolves to a single element: the matched element,
+   * or the first item when the selector matches multiple elements (a
+   * warning is logged in debug mode).
    *
    * @returns
-   * The a single element or a NodeList from the selector
+   * An HTMLElement, or null when the selector matches nothing
+   * (mirroring querySelector)
+   */
+
+  /**
+   *
+   * @function els
+   *
+   * @desc
+   * getter that always resolves to an Array of the matched elements.
+   *
+   * @returns
+   * An Array of HTMLElements; empty when the selector matches nothing
    */
 
   /**
@@ -312,7 +314,7 @@ function ViewStreamSelector(cxt, sel) {
    * Determines the length of the NodeList
    *
    * @returns
-   * The length of the selector as a NodeList
+   * The number of elements matched by the selector
    */
 
   /**
@@ -326,24 +328,27 @@ function ViewStreamSelector(cxt, sel) {
    * Boolean
    */
 
-  Object.defineProperty(selector, 'el', { get: () => getElOrList(cxt, sel, true) })
-  Object.defineProperty(selector, 'els', { get: () => getNodeListArray(cxt, sel) })
-  Object.defineProperty(selector, 'len', { get: () => getNodeListArray(cxt, sel, false).length })
-  Object.defineProperty(selector, 'exists', { get: () => getNodeListArray(cxt, sel, false).length >= 1 })
-  Object.defineProperty(selector, 'exist', { get: () => getNodeListArray(cxt, sel, false).length >= 1 })
-  Object.defineProperty(selector, 'nodeList', { get: () => getNodeListArray(cxt, sel) })
-  Object.defineProperty(selector, 'arr', {
+  const getElsArray = (verboseBool = true) => Array.from(getNodeListArray(cxt, sel, verboseBool))
+
+  Object.defineProperty(selector, 'el', {
     get: () => {
-      const el = getElOrList(cxt, sel, true)
-      if (el === undefined) {
-        return []
-      } else if (el.length === undefined) {
-        return [el]
-      } else {
-        return Array.from(el)
+      const list = getElsArray()
+      if (list.length > 1 && isDevMode() === true) {
+        spyneWarn(`Spyne Warning: el$("${sel !== undefined ? sel : cxt}").el matched ${list.length} elements; returning the first. Use .els for the full list.`)
       }
+      return list.length >= 1 ? list[0] : null
     }
   })
+  Object.defineProperty(selector, 'els', { get: () => getElsArray() })
+  Object.defineProperty(selector, 'arr', { get: () => getElsArray() })
+
+  // Undocumented. Retains the pre-0.24 polymorphic el contract — a single
+  // element, a NodeList, or an empty NodeList depending on match count —
+  // to assist in debugging and migrating older SpyneJS apps.
+  Object.defineProperty(selector, 'elLegacy', { get: () => getElOrList(cxt, sel, true) })
+  Object.defineProperty(selector, 'len', { get: () => getNodeListArray(cxt, sel, false).length })
+  Object.defineProperty(selector, 'length', { get: () => getNodeListArray(cxt, sel, false).length })
+  Object.defineProperty(selector, 'exists', { get: () => getNodeListArray(cxt, sel, false).length >= 1 })
 
   Object.defineProperty(selector, 'inline', { set: (val) => setInlineCss(val, cxt, sel), get: () => selector })
   Object.defineProperty(selector, 'inlineCss', { set: (val) => setInlineCss(val, cxt, sel), get: () => selector })

package/src/tests/channels/channel-payload-filter.test.js

@@ -191,6 +191,32 @@ describe('should test channel payload filters boolean correctness', () => {
 
     return true
   })
+
+  it('should return false for an invalid css selector instead of throwing', () => {
+    const cpFilter = new ChannelPayloadFilter('!!!not-a-selector')
+    const payloadBool = cpFilter(ChannelPayloadToTestFilters)
+    expect(payloadBool).to.be.false
+  })
+
+  it('should not match a structural lookalike of a selector match', () => {
+    // two identical siblings: the selector matches only the first, the
+    // payload el is the second — Element.matches tests the payload el
+    // itself, so the structurally equal non-matching twin must NOT pass
+    const ul = document.createElement('ul')
+    ul.innerHTML = '<li class="twin"><b>same</b></li><li class="twin"><b>same</b></li>'
+    document.body.appendChild(ul)
+    const cpFilter = new ChannelPayloadFilter('li.twin:first-child')
+    const payloadBool = cpFilter({ srcElement: { el: ul.querySelectorAll('li.twin')[1] } })
+    expect(payloadBool).to.be.false
+  })
+
+  it('should match a detached element against its selector', () => {
+    const li = document.createElement('li')
+    li.className = 'detached-item'
+    const cpFilter = new ChannelPayloadFilter('li.detached-item')
+    const payloadBool = cpFilter({ srcElement: { el: li } })
+    expect(payloadBool).to.be.true
+  })
 })
 
 describe('it should test channel payload filter with data packer ', () => {

package/src/tests/channels/channel-window-custom-events.test.js

@@ -0,0 +1,130 @@
+import { SpyneChannelWindow } from '../../spyne/channels/spyne-channel-window'
+import { Subject } from 'rxjs'
+const { expect } = require('chai')
+
+const conformedEvent = (detail) => {
+  const event = new CustomEvent('my_test_event', { detail })
+  return {
+    action: 'CHANNEL_WINDOW_MY_TEST_EVENT_EVENT',
+    payload: event,
+    srcElement: undefined,
+    event
+  }
+}
+
+describe('window channel customEvents config conforming', () => {
+  it('should conform a string entry', () => {
+    const entry = SpyneChannelWindow.conformCustomEventConfig('my_event')
+    expect(entry).to.deep.equal({ name: 'my_event', operator: undefined, value: undefined })
+  })
+
+  it('should conform an object entry with a buffer operator', () => {
+    const entry = SpyneChannelWindow.conformCustomEventConfig({ name: 'my_event', buffer: 400 })
+    expect(entry).to.deep.equal({ name: 'my_event', operator: 'buffer', value: 400 })
+  })
+
+  it('should conform debounce, throttle and count operators', () => {
+    expect(SpyneChannelWindow.conformCustomEventConfig({ name: 'e1', debounce: 250 }).operator).to.equal('debounce')
+    expect(SpyneChannelWindow.conformCustomEventConfig({ name: 'e2', throttle: 100 }).operator).to.equal('throttle')
+    expect(SpyneChannelWindow.conformCustomEventConfig({ name: 'e3', count: 50 }).operator).to.equal('count')
+  })
+
+  it('should pick the first operator when several are set', () => {
+    const entry = SpyneChannelWindow.conformCustomEventConfig({ name: 'my_event', debounce: 250, buffer: 400 })
+    expect(entry.operator).to.equal('buffer')
+    expect(entry.value).to.equal(400)
+  })
+
+  it('should skip invalid entries', () => {
+    expect(SpyneChannelWindow.conformCustomEventConfig(42)).to.equal(null)
+    expect(SpyneChannelWindow.conformCustomEventConfig({ buffer: 400 })).to.equal(null)
+    expect(SpyneChannelWindow.conformCustomEventConfig(null)).to.equal(null)
+  })
+})
+
+describe('window channel customEvents batching operators', () => {
+  it('should map a batch to one payload with detail as the details array', () => {
+    const batch = [conformedEvent({ id: 1 }), conformedEvent({ id: 2 }), conformedEvent({ id: 3 })]
+    const { action, payload, event } = SpyneChannelWindow.mapBatchedEvents(batch)
+    expect(action).to.equal('CHANNEL_WINDOW_MY_TEST_EVENT_EVENT')
+    expect(payload.detail).to.deep.equal([{ id: 1 }, { id: 2 }, { id: 3 }])
+    expect(payload.isBatch).to.be.true
+    expect(payload.batchCount).to.equal(3)
+    expect(event).to.equal(batch[2].event)
+  })
+
+  it('should close a buffer batch after the quiet gap and emit once', (done) => {
+    const source$ = new Subject()
+    const obs$ = SpyneChannelWindow.customizeCustomEventObservable(source$, 'buffer', 30)
+    const emissions = []
+    obs$.subscribe(p => emissions.push(p))
+
+    source$.next(conformedEvent({ id: 1 }))
+    source$.next(conformedEvent({ id: 2 }))
+    setTimeout(() => source$.next(conformedEvent({ id: 3 })), 10)
+
+    setTimeout(() => {
+      expect(emissions.length).to.equal(1)
+      expect(emissions[0].payload.detail).to.deep.equal([{ id: 1 }, { id: 2 }, { id: 3 }])
+      done()
+    }, 100)
+  })
+
+  it('should emit separate buffer batches per burst', (done) => {
+    const source$ = new Subject()
+    const obs$ = SpyneChannelWindow.customizeCustomEventObservable(source$, 'buffer', 20)
+    const emissions = []
+    obs$.subscribe(p => emissions.push(p))
+
+    source$.next(conformedEvent({ id: 1 }))
+    setTimeout(() => source$.next(conformedEvent({ id: 2 })), 60)
+
+    setTimeout(() => {
+      expect(emissions.length).to.equal(2)
+      expect(emissions[0].payload.batchCount).to.equal(1)
+      expect(emissions[1].payload.batchCount).to.equal(1)
+      done()
+    }, 140)
+  })
+
+  it('should batch every n events with the count operator', () => {
+    const source$ = new Subject()
+    const obs$ = SpyneChannelWindow.customizeCustomEventObservable(source$, 'count', 2)
+    const emissions = []
+    obs$.subscribe(p => emissions.push(p))
+
+    source$.next(conformedEvent({ id: 1 }))
+    source$.next(conformedEvent({ id: 2 }))
+    source$.next(conformedEvent({ id: 3 }))
+    source$.next(conformedEvent({ id: 4 }))
+    source$.next(conformedEvent({ id: 5 }))
+
+    expect(emissions.length).to.equal(2)
+    expect(emissions[0].payload.detail).to.deep.equal([{ id: 1 }, { id: 2 }])
+    expect(emissions[1].payload.detail).to.deep.equal([{ id: 3 }, { id: 4 }])
+  })
+
+  it('should pass only the latest event through debounce', (done) => {
+    const source$ = new Subject()
+    const obs$ = SpyneChannelWindow.customizeCustomEventObservable(source$, 'debounce', 20)
+    const emissions = []
+    obs$.subscribe(p => emissions.push(p))
+
+    source$.next(conformedEvent({ id: 1 }))
+    source$.next(conformedEvent({ id: 2 }))
+    source$.next(conformedEvent({ id: 3 }))
+
+    setTimeout(() => {
+      expect(emissions.length).to.equal(1)
+      // debounced events keep the single-event payload shape (payload = CustomEvent)
+      expect(emissions[0].payload.detail).to.deep.equal({ id: 3 })
+      done()
+    }, 80)
+  })
+
+  it('should return the observable untouched when there is no operator', () => {
+    const source$ = new Subject()
+    const obs$ = SpyneChannelWindow.customizeCustomEventObservable(source$, undefined, undefined)
+    expect(obs$).to.equal(source$)
+  })
+})

package/src/tests/index.test.js

@@ -1,3 +1,8 @@
+// Silence SpyneJS developer-hint warnings across all test bundles.
+// Expected-failure cases (invalid selectors, blocked URIs, policy removals)
+// would otherwise flood the karma reporter. Security warnings still print.
+window.SPYNE_SUPPRESS_WARNINGS = true
+
 import { SpyneApp } from '../spyne/spyne'
 
 // import {AppView} from "../app/app-view";