Merge pull request #64 from github/feat-add-loading-lazy

Feat add loading lazy

Author: keithamus

README.md

@@ -40,6 +40,21 @@ On page load, the `include-fragment` element fetches the URL, the response is pa
 
 The server must respond with an HTML fragment to replace the `include-fragment` element. It should not contain _another_ `include-fragment` element or the server will be polled in an infinite loop.
 
+### Other Attributes
+
+#### accept
+
+This attribute tells `<include-fragment/>` what to send as the `Accept` header, as part of the fetch request. If omitted, or if set to an empty value, the default behaviour will be `text/html`. It is important that the server responds with HTML, but you may wish to change the accept header to help negotiate the right content with the server.
+
+#### loading
+
+This indicates _when_ the contents should be fetched:
+
+ - `eager`: Fetches and load the content immediately, regardless of whether or not the `<include-fragment/>` is currently within the visible viewport (this is the default value).
+ - `lazy`: Defers fetching and loading the content until the `<include-fragment/>` tag reaches a calculated distance from the viewport. The intent is to avoid the network and storage bandwidth needed to handle the content until it's reasonably certain that it will be needed.
+
+The 
+
 ### Errors
 
 If the URL fails to load, the `include-fragment` element is left in the page and tagged with an `is-error` CSS class that can be used for styling.

examples/index.html

@@ -8,5 +8,9 @@
   <include-fragment src="./pull.html">Loading</include-fragment>
   <!-- <script type="module" src="../dist/index.js"></script> -->
   <script type="module" src="https://unpkg.com/@github/include-fragment-element@latest?module"></script>
+  <details>
+    <summary>Click to unfold a lazy include-fragment</summary>
+    <include-fragment src="./pull.html" loading="lazy">Loading</include-fragment>
+  </details>
 </body>
 </html>

src/index.ts

@@ -1,12 +1,34 @@
 const privateData = new WeakMap()
 
+const observer = new IntersectionObserver(entries => {
+  for(const entry of entries) {
+    if (entry.isIntersecting) {
+      const {target} = entry 
+      observer.unobserve(target)
+      if (!(target instanceof IncludeFragmentElement)) return
+      if (target.loading === 'lazy') {
+        handleData(target)
+      }
+    }
+  }
+}, {
+  // Currently the threshold is set to 256px from the bottom of the viewport
+  // with a threshold of 0.1. This means the element will not load until about
+  // 2 keyboard-down-arrow presses away from being visible in the viewport,
+  // giving us some time to fetch it before the contents are made visible
+  rootMargin: '0px 0px 256px 0px',
+  threshold: 0.01
+})
+
+
 function fire(name: string, target: Element) {
   setTimeout(function () {
     target.dispatchEvent(new Event(name))
   }, 0)
 }
 
 async function handleData(el: IncludeFragmentElement) {
+  observer.unobserve(el)
   // eslint-disable-next-line github/no-then
   return getData(el).then(
     function (html: string) {
@@ -47,7 +69,7 @@ function isWildcard(accept: string | null) {
 export default class IncludeFragmentElement extends HTMLElement {
 
   static get observedAttributes(): string[] {
-    return ['src']
+    return ['src', 'loading']
   }
 
   get src(): string {
@@ -65,6 +87,15 @@ export default class IncludeFragmentElement extends HTMLElement {
     this.setAttribute('src', val)
   }
 
+  get loading(): 'eager'|'lazy'  {
+    if (this.getAttribute('loading') === 'lazy') return 'lazy'
+    return 'eager'
+  }
+
+  set loading(value: 'eager'|'lazy') {
+    this.setAttribute('loading', value)
+  }
+
   get accept(): string {
     return this.getAttribute('accept') || ''
   }
@@ -77,19 +108,27 @@ export default class IncludeFragmentElement extends HTMLElement {
     return getData(this)
   }
 
-  attributeChangedCallback(attribute: string): void {
+  attributeChangedCallback(attribute: string, oldVal:string|null): void {
     if (attribute === 'src') {
       // Source changed after attached so replace element.
-      if (this.isConnected) {
+      if (this.isConnected && this.loading === 'eager') {
+        handleData(this)
+      }
+    } else if (attribute === 'loading') {
+      // Loading mode changed to Eager after attached so replace element.
+      if (this.isConnected && oldVal !== 'eager' && this.loading === 'eager') {
         handleData(this)
       }
     }
   }
 
   connectedCallback(): void {
-    if (this.src) {
+    if (this.src && this.loading === 'eager') {
       handleData(this)
     }
+    if (this.loading === 'lazy') {
+      observer.observe(this)
+    }
   }
 
   request(): Request {
@@ -108,6 +147,7 @@ export default class IncludeFragmentElement extends HTMLElement {
   }
 
   load(): Promise<string> {
+    observer.unobserve(this)
     return Promise.resolve()
       .then(() => {
         fire('loadstart', this)

test/test.js

@@ -10,6 +10,11 @@ const responses = {
       }
     })
   },
+  '/slow-hello': function() {
+    return new Promise(resolve => {
+      setTimeout(resolve, 100)
+    }).then(responses['/hello'])
+  },
   '/one-two': function() {
     return new Response('<p id="one">one</p><p id="two">two</p>', {
       status: 200,
@@ -372,7 +377,7 @@ suite('include-fragment-element', function() {
     })
   })
 
-  test.only('fires replaced event', function() {
+  test('fires replaced event', function() {
     const elem = document.createElement('include-fragment')
     document.body.appendChild(elem)
 
@@ -386,7 +391,7 @@ suite('include-fragment-element', function() {
     })
   })
 
-  test.only('fires events for include-fragment node replacement operations for fragment manipulation', function() {
+  test('fires events for include-fragment node replacement operations for fragment manipulation', function() {
     const elem = document.createElement('include-fragment')
     document.body.appendChild(elem)
 
@@ -404,7 +409,7 @@ suite('include-fragment-element', function() {
     })
   })
 
-  test.only('does not replace node if event was canceled ', function() {
+  test('does not replace node if event was canceled ', function() {
     const elem = document.createElement('include-fragment')
     document.body.appendChild(elem)
 
@@ -420,4 +425,127 @@ suite('include-fragment-element', function() {
       assert(document.querySelector('include-fragment'), 'Node should not be replaced')
     })
   })
+
+  test('sets loading to "eager" by default', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    document.body.appendChild(div)
+
+    assert(div.firstChild.loading, 'eager')
+  })
+
+  test('loading will return "eager" even if set to junk value', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="junk" src="/hello">loading</include-fragment>'
+    document.body.appendChild(div)
+
+    assert(div.firstChild.loading, 'eager')
+  })
+
+  test('loading=lazy loads if already visible on page', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    document.body.appendChild(div)
+    
+    return when(div.firstChild, 'include-fragment-replaced').then(() => {
+      assert.equal(document.querySelector('include-fragment'), null)
+      assert.equal(document.querySelector('#replaced').textContent, 'hello')
+    })
+  })
+
+  test('loading=lazy does not load if not visible on page', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    div.hidden = true
+    document.body.appendChild(div)
+    return Promise.race([
+      when(div.firstChild, 'load').then(() => {
+        throw new Error('<include-fragment loading=lazy> loaded too early')
+      }),
+      new Promise(resolve => setTimeout(resolve, 100))
+    ])
+  })
+
+  test('loading=lazy does not load when src is changed', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="">loading</include-fragment>'
+    div.hidden = true
+    document.body.appendChild(div)
+    div.firstChild.src = '/hello'
+    return Promise.race([
+      when(div.firstChild, 'load').then(() => {
+        throw new Error('<include-fragment loading=lazy> loaded too early')
+      }),
+      new Promise(resolve => setTimeout(resolve, 100))
+    ])
+  })
+
+
+  test('loading=lazy loads as soon as element visible on page', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    div.hidden = true
+    let failed = false
+    document.body.appendChild(div)
+    const fail = () => failed = true
+    div.firstChild.addEventListener('load', fail)
+
+    setTimeout(function() {
+      div.hidden = false
+      div.firstChild.removeEventListener('load', fail)
+    }, 100)
+
+    return when(div.firstChild, 'load').then(() => {
+      assert.ok(!failed, "Load occured too early")
+    })
+  })
+
+  test('loading=lazy does not observably change during load cycle', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    const elem = div.firstChild
+    document.body.appendChild(div)
+
+    return when(elem, 'loadstart').then(() => {
+      assert.equal(elem.loading, 'lazy', "loading mode changed observably")
+    })
+  })
+
+  test('loading=lazy can be switched to eager to load', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/hello">loading</include-fragment>'
+    div.hidden = true
+    let failed = false
+    document.body.appendChild(div)
+    const fail = () => failed = true
+    div.firstChild.addEventListener('load', fail)
+
+    setTimeout(function() {
+      div.firstChild.loading = 'eager'
+      div.firstChild.removeEventListener('load', fail)
+    }, 100)
+
+    return when(div.firstChild, 'load').then(() => {
+      assert.ok(!failed, "Load occured too early")
+    })
+  })
+
+  test('loading=lazy wont load twice even if load is manually called', function() {
+    const div = document.createElement('div')
+    div.innerHTML = '<include-fragment loading="lazy" src="/slow-hello">loading</include-fragment>'
+    div.hidden = true
+    document.body.appendChild(div)
+    let count = 0
+    div.firstChild.addEventListener('loadstart', () => count += 1)
+    const load = div.firstChild.load()
+    setTimeout(() => {
+      div.hidden = false
+    }, 0)
+
+    return load
+      .then(() => when(div.firstChild, 'loadend'))
+      .then(() => {
+        assert.equal(count, 1, "Load occured too many times")
+      })
+  })
 })