@furystack/shades 11.1.0 → 12.0.0

package/src/shade-resources.integration.spec.tsx

@@ -1,9 +1,9 @@
 import { Injector } from '@furystack/inject'
-import { ObservableValue, sleepAsync } from '@furystack/utils'
+import { ObservableValue, sleepAsync, usingAsync } from '@furystack/utils'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { initializeShadeRoot } from './initialize.js'
 import { createComponent } from './shade-component.js'
-import { Shade } from './shade.js'
+import { flushUpdates, Shade } from './shade.js'
 
 describe('Shade Resources integration tests', () => {
   beforeEach(() => {
@@ -14,68 +14,292 @@ describe('Shade Resources integration tests', () => {
   })
 
   it('Should update the component based on a custom observable value change', async () => {
-    const injector = new Injector()
-    const rootElement = document.getElementById('root') as HTMLDivElement
-
-    const renderCounter = vi.fn()
-
-    const obs1 = new ObservableValue(0)
-    const obs2 = new ObservableValue('a')
-
-    const ExampleComponent = Shade({
-      render: ({ useObservable }) => {
-        const [value1] = useObservable('obs1', obs1)
-        const [value2] = useObservable('obs2', obs2)
-
-        renderCounter()
-        return (
-          <div>
-            <div id="val1">{value1}</div>
-            <div id="val2">{value2}</div>
-          </div>
-        )
-      },
-      shadowDomName: 'shades-example-resource',
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const renderCounter = vi.fn()
+
+      const obs1 = new ObservableValue(0)
+      const obs2 = new ObservableValue('a')
+
+      const ExampleComponent = Shade({
+        render: ({ useObservable }) => {
+          const [value1] = useObservable('obs1', obs1)
+          const [value2] = useObservable('obs2', obs2)
+
+          renderCounter()
+          return (
+            <div>
+              <div id="val1">{value1}</div>
+              <div id="val2">{value2}</div>
+            </div>
+          )
+        },
+        shadowDomName: 'shades-example-resource',
+      })
+
+      expect(obs1.getObservers().length).toBe(0)
+      expect(obs2.getObservers().length).toBe(0)
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+      expect(document.body.innerHTML).toBe(
+        '<div id="root"><shades-example-resource><div><div id="val1">0</div><div id="val2">a</div></div></shades-example-resource></div>',
+      )
+
+      expect(obs1.getObservers().length).toBe(1)
+      expect(obs2.getObservers().length).toBe(1)
+
+      expect(renderCounter).toBeCalledTimes(1)
+
+      obs1.setValue(1)
+      await flushUpdates()
+      expect(document.body.innerHTML).toBe(
+        '<div id="root"><shades-example-resource><div><div id="val1">1</div><div id="val2">a</div></div></shades-example-resource></div>',
+      )
+      expect(renderCounter).toBeCalledTimes(2)
+
+      obs2.setValue('b')
+      await flushUpdates()
+      expect(document.body.innerHTML).toBe(
+        '<div id="root"><shades-example-resource><div><div id="val1">1</div><div id="val2">b</div></div></shades-example-resource></div>',
+      )
+
+      const element = document.querySelector('shades-example-resource') as JSX.Element
+      expect(element.getRenderCount()).toBe(3)
+
+      document.body.innerHTML = ''
+
+      await sleepAsync(10) // Cleanup can be async
+
+      expect(obs1.getObservers().length).toBe(0)
+      expect(obs2.getObservers().length).toBe(0)
+
+      expect(renderCounter).toBeCalledTimes(3)
     })
+  })
+
+  it('Should NOT re-render the component when a custom onChange callback is provided', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const renderCounter = vi.fn()
+      const customOnChange = vi.fn()
+
+      const obs = new ObservableValue(0)
+
+      const ExampleComponent = Shade({
+        render: ({ useObservable }) => {
+          const [value] = useObservable('obs', obs, { onChange: customOnChange })
+
+          renderCounter()
+          return <div id="val">{value}</div>
+        },
+        shadowDomName: 'shades-example-custom-onchange',
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const element = document.querySelector('shades-example-custom-onchange') as JSX.Element
 
-    expect(obs1.getObservers().length).toBe(0)
-    expect(obs2.getObservers().length).toBe(0)
+      // Initial render
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+      expect(customOnChange).toBeCalledTimes(0) // Not called until value changes
+      expect(document.getElementById('val')?.textContent).toBe('0')
 
-    initializeShadeRoot({
-      injector,
-      rootElement,
-      jsxElement: <ExampleComponent />,
+      // Change the observable value
+      obs.setValue(1)
+
+      // Custom onChange should be called
+      expect(customOnChange).toBeCalledTimes(1)
+      expect(customOnChange).toHaveBeenLastCalledWith(1)
+
+      // But component should NOT re-render
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+
+      // DOM should still show old value since no re-render occurred
+      expect(document.getElementById('val')?.textContent).toBe('0')
+
+      // Change again to verify consistent behavior
+      obs.setValue(2)
+
+      expect(customOnChange).toBeCalledTimes(2)
+      expect(customOnChange).toHaveBeenLastCalledWith(2)
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
     })
-    expect(document.body.innerHTML).toBe(
-      '<div id="root"><shades-example-resource><div><div id="val1">0</div><div id="val2">a</div></div></shades-example-resource></div>',
-    )
+  })
 
-    expect(obs1.getObservers().length).toBe(1)
-    expect(obs2.getObservers().length).toBe(1)
+  it('Should allow manual DOM updates in custom onChange callback without re-render', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
 
-    expect(renderCounter).toBeCalledTimes(1)
+      const renderCounter = vi.fn()
+      const obs = new ObservableValue(0)
 
-    obs1.setValue(1)
-    expect(document.body.innerHTML).toBe(
-      '<div id="root"><shades-example-resource><div><div id="val1">1</div><div id="val2">a</div></div></shades-example-resource></div>',
-    )
-    expect(renderCounter).toBeCalledTimes(2)
+      const ExampleComponent = Shade({
+        render: ({ useObservable, useRef }) => {
+          const valRef = useRef<HTMLDivElement>('manualVal')
+          useObservable('obs', obs, {
+            onChange: (newValue) => {
+              if (valRef.current) {
+                valRef.current.textContent = String(newValue)
+              }
+            },
+          })
 
-    obs2.setValue('b')
-    expect(document.body.innerHTML).toBe(
-      '<div id="root"><shades-example-resource><div><div id="val1">1</div><div id="val2">b</div></div></shades-example-resource></div>',
-    )
+          renderCounter()
+          return (
+            <div ref={valRef} id="manual-val">
+              {obs.getValue()}
+            </div>
+          )
+        },
+        shadowDomName: 'shades-example-manual-dom-update',
+      })
 
-    const element = document.querySelector('shades-example-resource') as JSX.Element
-    expect(element.getRenderCount()).toBe(3)
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
 
-    document.body.innerHTML = ''
+      const element = document.querySelector('shades-example-manual-dom-update') as JSX.Element
 
-    await sleepAsync(10) // Cleanup can be async
+      // Initial render
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+      expect(document.getElementById('manual-val')?.textContent).toBe('0')
 
-    expect(obs1.getObservers().length).toBe(0)
-    expect(obs2.getObservers().length).toBe(0)
+      // Change the observable value
+      obs.setValue(42)
 
-    expect(renderCounter).toBeCalledTimes(3)
+      // Component should NOT re-render
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+
+      // But DOM should be updated via the manual onChange callback
+      expect(document.getElementById('manual-val')?.textContent).toBe('42')
+
+      // Change again
+      obs.setValue(100)
+
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+      expect(document.getElementById('manual-val')?.textContent).toBe('100')
+    })
+  })
+
+  it('Should batch multiple synchronous observable changes into a single render', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const renderCounter = vi.fn()
+
+      const obs1 = new ObservableValue(0)
+      const obs2 = new ObservableValue('a')
+      const obs3 = new ObservableValue(false)
+
+      const ExampleComponent = Shade({
+        render: ({ useObservable }) => {
+          const [value1] = useObservable('obs1', obs1)
+          const [value2] = useObservable('obs2', obs2)
+          const [value3] = useObservable('obs3', obs3)
+
+          renderCounter()
+          return (
+            <div>
+              <span id="v1">{value1}</span>
+              <span id="v2">{value2}</span>
+              <span id="v3">{String(value3)}</span>
+            </div>
+          )
+        },
+        shadowDomName: 'shades-example-batching',
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const element = document.querySelector('shades-example-batching') as JSX.Element
+
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+
+      // Change all three observables synchronously without awaiting in between
+      obs1.setValue(42)
+      obs2.setValue('z')
+      obs3.setValue(true)
+
+      // Before flushing, the DOM should still reflect the old values
+      expect(element.getRenderCount()).toBe(1)
+
+      await flushUpdates()
+
+      // After flushing, all changes should be reflected in a single render
+      expect(element.getRenderCount()).toBe(2)
+      expect(renderCounter).toBeCalledTimes(2)
+      expect(document.getElementById('v1')?.textContent).toBe('42')
+      expect(document.getElementById('v2')?.textContent).toBe('z')
+      expect(document.getElementById('v3')?.textContent).toBe('true')
+    })
+  })
+
+  it('Should batch multiple updateComponent() calls into a single render', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      const renderCounter = vi.fn()
+
+      const ExampleComponent = Shade({
+        render: () => {
+          renderCounter()
+          return <div>content</div>
+        },
+        shadowDomName: 'shades-example-update-batching',
+      })
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <ExampleComponent />,
+      })
+      await flushUpdates()
+
+      const element = document.querySelector('shades-example-update-batching') as JSX.Element
+
+      expect(element.getRenderCount()).toBe(1)
+      expect(renderCounter).toBeCalledTimes(1)
+
+      // Call updateComponent multiple times synchronously
+      element.updateComponent()
+      element.updateComponent()
+      element.updateComponent()
+
+      // Before flushing, render count should still be 1
+      expect(element.getRenderCount()).toBe(1)
+
+      await flushUpdates()
+
+      // After flushing, only a single additional render should have occurred
+      expect(element.getRenderCount()).toBe(2)
+      expect(renderCounter).toBeCalledTimes(2)
+    })
   })
 })

package/src/shade.spec.tsx

@@ -27,7 +27,7 @@ describe('Shade edge cases', () => {
           shadowDomName: 'shade-duplicate-test',
           render: () => <div>Second</div>,
         })
-      }).toThrow("A custom shade with shadow DOM name 'shade-duplicate-test' has already been registered!")
+      }).toThrow("A custom shade with name 'shade-duplicate-test' has already been registered!")
     })
 
     it('should include the duplicate name in the error message', () => {
@@ -54,45 +54,46 @@ describe('Shade edge cases', () => {
   describe('injector from props', () => {
     it('should use props injector for child component instead of inheriting from parent', async () => {
       await usingAsync(new Injector(), async (rootInjector) => {
-        const propsInjector = new Injector()
-        const rootElement = document.getElementById('root') as HTMLDivElement
-
-        let parentCapturedInjector: Injector | undefined
-        let childCapturedInjector: Injector | undefined
-
-        const ChildComponent = Shade<{ injector?: Injector }>({
-          shadowDomName: 'shade-injector-child-props-test',
-          render: ({ injector }) => {
-            childCapturedInjector = injector
-            return <div>Child</div>
-          },
-        })
-
-        const ParentComponent = Shade({
-          shadowDomName: 'shade-injector-parent-props-test',
-          render: ({ injector, children }) => {
-            parentCapturedInjector = injector
-            return <div>{children}</div>
-          },
+        await usingAsync(new Injector(), async (propsInjector) => {
+          const rootElement = document.getElementById('root') as HTMLDivElement
+
+          let parentCapturedInjector: Injector | undefined
+          let childCapturedInjector: Injector | undefined
+
+          const ChildComponent = Shade<{ injector?: Injector }>({
+            shadowDomName: 'shade-injector-child-props-test',
+            render: ({ injector }) => {
+              childCapturedInjector = injector
+              return <div>Child</div>
+            },
+          })
+
+          const ParentComponent = Shade({
+            shadowDomName: 'shade-injector-parent-props-test',
+            render: ({ injector, children }) => {
+              parentCapturedInjector = injector
+              return <div>{children}</div>
+            },
+          })
+
+          initializeShadeRoot({
+            injector: rootInjector,
+            rootElement,
+            jsxElement: (
+              <ParentComponent>
+                <ChildComponent injector={propsInjector} />
+              </ParentComponent>
+            ),
+          })
+
+          await sleepAsync(10)
+
+          // Parent should use root injector (inherited from parent)
+          expect(parentCapturedInjector).toBe(rootInjector)
+          // Child should use the props injector, not the parent's
+          expect(childCapturedInjector).toBe(propsInjector)
+          expect(childCapturedInjector).not.toBe(rootInjector)
         })
-
-        initializeShadeRoot({
-          injector: rootInjector,
-          rootElement,
-          jsxElement: (
-            <ParentComponent>
-              <ChildComponent injector={propsInjector} />
-            </ParentComponent>
-          ),
-        })
-
-        await sleepAsync(10)
-
-        // Parent should use root injector (inherited from parent)
-        expect(parentCapturedInjector).toBe(rootInjector)
-        // Child should use the props injector, not the parent's
-        expect(childCapturedInjector).toBe(propsInjector)
-        expect(childCapturedInjector).not.toBe(rootInjector)
       })
     })
   })