@furystack/shades 11.1.0 → 12.0.0

package/esm/shade-resources.integration.spec.js

@@ -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(() => {
         document.body.innerHTML = '<div id="root"></div>';
@@ -12,45 +12,214 @@ describe('Shade Resources integration tests', () => {
         document.body.innerHTML = '';
     });
     it('Should update the component based on a custom observable value change', async () => {
-        const injector = new Injector();
-        const rootElement = document.getElementById('root');
-        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 (createComponent("div", null,
-                    createComponent("div", { id: "val1" }, value1),
-                    createComponent("div", { id: "val2" }, value2)));
-            },
-            shadowDomName: 'shades-example-resource',
+        await usingAsync(new Injector(), async (injector) => {
+            const rootElement = document.getElementById('root');
+            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 (createComponent("div", null,
+                        createComponent("div", { id: "val1" }, value1),
+                        createComponent("div", { id: "val2" }, value2)));
+                },
+                shadowDomName: 'shades-example-resource',
+            });
+            expect(obs1.getObservers().length).toBe(0);
+            expect(obs2.getObservers().length).toBe(0);
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: createComponent(ExampleComponent, null),
+            });
+            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');
+            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);
         });
-        expect(obs1.getObservers().length).toBe(0);
-        expect(obs2.getObservers().length).toBe(0);
-        initializeShadeRoot({
-            injector,
-            rootElement,
-            jsxElement: createComponent(ExampleComponent, null),
+    });
+    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');
+            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 createComponent("div", { id: "val" }, value);
+                },
+                shadowDomName: 'shades-example-custom-onchange',
+            });
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: createComponent(ExampleComponent, null),
+            });
+            await flushUpdates();
+            const element = document.querySelector('shades-example-custom-onchange');
+            // 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');
+            // 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);
+        });
+    });
+    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');
+            const renderCounter = vi.fn();
+            const obs = new ObservableValue(0);
+            const ExampleComponent = Shade({
+                render: ({ useObservable, useRef }) => {
+                    const valRef = useRef('manualVal');
+                    useObservable('obs', obs, {
+                        onChange: (newValue) => {
+                            if (valRef.current) {
+                                valRef.current.textContent = String(newValue);
+                            }
+                        },
+                    });
+                    renderCounter();
+                    return (createComponent("div", { ref: valRef, id: "manual-val" }, obs.getValue()));
+                },
+                shadowDomName: 'shades-example-manual-dom-update',
+            });
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: createComponent(ExampleComponent, null),
+            });
+            await flushUpdates();
+            const element = document.querySelector('shades-example-manual-dom-update');
+            // Initial render
+            expect(element.getRenderCount()).toBe(1);
+            expect(renderCounter).toBeCalledTimes(1);
+            expect(document.getElementById('manual-val')?.textContent).toBe('0');
+            // Change the observable value
+            obs.setValue(42);
+            // 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');
+            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 (createComponent("div", null,
+                        createComponent("span", { id: "v1" }, value1),
+                        createComponent("span", { id: "v2" }, value2),
+                        createComponent("span", { id: "v3" }, String(value3))));
+                },
+                shadowDomName: 'shades-example-batching',
+            });
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: createComponent(ExampleComponent, null),
+            });
+            await flushUpdates();
+            const element = document.querySelector('shades-example-batching');
+            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');
+            const renderCounter = vi.fn();
+            const ExampleComponent = Shade({
+                render: () => {
+                    renderCounter();
+                    return createComponent("div", null, "content");
+                },
+                shadowDomName: 'shades-example-update-batching',
+            });
+            initializeShadeRoot({
+                injector,
+                rootElement,
+                jsxElement: createComponent(ExampleComponent, null),
+            });
+            await flushUpdates();
+            const element = document.querySelector('shades-example-update-batching');
+            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);
         });
-        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);
-        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');
-        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');
-        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);
     });
 });
 //# sourceMappingURL=shade-resources.integration.spec.js.map

package/esm/shade-resources.integration.spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"shade-resources.integration.spec.js","sourceRoot":"","sources":["../src/shade-resources.integration.spec.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"shade-resources.integration.spec.js","sourceRoot":"","sources":["../src/shade-resources.integration.spec.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC1E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhD,QAAQ,CAAC,mCAAmC,EAAE,GAAG,EAAE;IACjD,UAAU,CAAC,GAAG,EAAE;QACd,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,uBAAuB,CAAA;IACnD,CAAC,CAAC,CAAA;IACF,SAAS,CAAC,GAAG,EAAE;QACb,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAA;IAC9B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uEAAuE,EAAE,KAAK,IAAI,EAAE;QACrF,MAAM,UAAU,CAAC,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAmB,CAAA;YAErE,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAE7B,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAA;YACnC,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,CAAA;YAErC,MAAM,gBAAgB,GAAG,KAAK,CAAC;gBAC7B,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE;oBAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;oBAC5C,MAAM,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;oBAE5C,aAAa,EAAE,CAAA;oBACf,OAAO,CACL;wBACE,yBAAK,EAAE,EAAC,MAAM,IAAE,MAAM,CAAO;wBAC7B,yBAAK,EAAE,EAAC,MAAM,IAAE,MAAM,CAAO,CACzB,CACP,CAAA;gBACH,CAAC;gBACD,aAAa,EAAE,yBAAyB;aACzC,CAAC,CAAA;YAEF,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1C,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAE1C,mBAAmB,CAAC;gBAClB,QAAQ;gBACR,WAAW;gBACX,UAAU,EAAE,gBAAC,gBAAgB,OAAG;aACjC,CAAC,CAAA;YACF,MAAM,YAAY,EAAE,CAAA;YACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAClC,iIAAiI,CAClI,CAAA;YAED,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1C,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAE1C,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAChB,MAAM,YAAY,EAAE,CAAA;YACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAClC,iIAAiI,CAClI,CAAA;YACD,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;YAClB,MAAM,YAAY,EAAE,CAAA;YACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAClC,iIAAiI,CAClI,CAAA;YAED,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,yBAAyB,CAAgB,CAAA;YAChF,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAExC,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,EAAE,CAAA;YAE5B,MAAM,UAAU,CAAC,EAAE,CAAC,CAAA,CAAC,uBAAuB;YAE5C,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1C,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAE1C,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;QAC1C,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gFAAgF,EAAE,KAAK,IAAI,EAAE;QAC9F,MAAM,UAAU,CAAC,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAmB,CAAA;YAErE,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAC7B,MAAM,cAAc,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAE9B,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAA;YAElC,MAAM,gBAAgB,GAAG,KAAK,CAAC;gBAC7B,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE;oBAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAA;oBAEvE,aAAa,EAAE,CAAA;oBACf,OAAO,yBAAK,EAAE,EAAC,KAAK,IAAE,KAAK,CAAO,CAAA;gBACpC,CAAC;gBACD,aAAa,EAAE,gCAAgC;aAChD,CAAC,CAAA;YAEF,mBAAmB,CAAC;gBAClB,QAAQ;gBACR,WAAW;gBACX,UAAU,EAAE,gBAAC,gBAAgB,OAAG;aACjC,CAAC,CAAA;YACF,MAAM,YAAY,EAAE,CAAA;YAEpB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,gCAAgC,CAAgB,CAAA;YAEvF,iBAAiB;YACjB,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA,CAAC,iCAAiC;YAC3E,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAE7D,8BAA8B;YAC9B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAEf,mCAAmC;YACnC,MAAM,CAAC,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACzC,MAAM,CAAC,cAAc,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAA;YAElD,qCAAqC;YACrC,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,8DAA8D;YAC9D,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAE7D,6CAA6C;YAC7C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAEf,MAAM,CAAC,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACzC,MAAM,CAAC,cAAc,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,CAAA;YAClD,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;QAC1C,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+EAA+E,EAAE,KAAK,IAAI,EAAE;QAC7F,MAAM,UAAU,CAAC,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAmB,CAAA;YAErE,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAC7B,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAA;YAElC,MAAM,gBAAgB,GAAG,KAAK,CAAC;gBAC7B,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,EAAE;oBACpC,MAAM,MAAM,GAAG,MAAM,CAAiB,WAAW,CAAC,CAAA;oBAClD,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE;wBACxB,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE;4BACrB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gCACnB,MAAM,CAAC,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;4BAC/C,CAAC;wBACH,CAAC;qBACF,CAAC,CAAA;oBAEF,aAAa,EAAE,CAAA;oBACf,OAAO,CACL,yBAAK,GAAG,EAAE,MAAM,EAAE,EAAE,EAAC,YAAY,IAC9B,GAAG,CAAC,QAAQ,EAAE,CACX,CACP,CAAA;gBACH,CAAC;gBACD,aAAa,EAAE,kCAAkC;aAClD,CAAC,CAAA;YAEF,mBAAmB,CAAC;gBAClB,QAAQ;gBACR,WAAW;gBACX,UAAU,EAAE,gBAAC,gBAAgB,OAAG;aACjC,CAAC,CAAA;YACF,MAAM,YAAY,EAAE,CAAA;YAEpB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,kCAAkC,CAAgB,CAAA;YAEzF,iBAAiB;YACjB,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAEpE,8BAA8B;YAC9B,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YAEhB,iCAAiC;YACjC,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,6DAA6D;YAC7D,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAErE,eAAe;YACf,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;YAEjB,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxE,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2EAA2E,EAAE,KAAK,IAAI,EAAE;QACzF,MAAM,UAAU,CAAC,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAmB,CAAA;YAErE,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAE7B,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,CAAC,CAAC,CAAA;YACnC,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,CAAA;YACrC,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAA;YAEvC,MAAM,gBAAgB,GAAG,KAAK,CAAC;gBAC7B,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE;oBAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;oBAC5C,MAAM,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;oBAC5C,MAAM,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;oBAE5C,aAAa,EAAE,CAAA;oBACf,OAAO,CACL;wBACE,0BAAM,EAAE,EAAC,IAAI,IAAE,MAAM,CAAQ;wBAC7B,0BAAM,EAAE,EAAC,IAAI,IAAE,MAAM,CAAQ;wBAC7B,0BAAM,EAAE,EAAC,IAAI,IAAE,MAAM,CAAC,MAAM,CAAC,CAAQ,CACjC,CACP,CAAA;gBACH,CAAC;gBACD,aAAa,EAAE,yBAAyB;aACzC,CAAC,CAAA;YAEF,mBAAmB,CAAC;gBAClB,QAAQ;gBACR,WAAW;gBACX,UAAU,EAAE,gBAAC,gBAAgB,OAAG;aACjC,CAAC,CAAA;YACF,MAAM,YAAY,EAAE,CAAA;YAEpB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,yBAAyB,CAAgB,CAAA;YAEhF,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,yEAAyE;YACzE,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YACjB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;YAClB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;YAEnB,+DAA+D;YAC/D,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAExC,MAAM,YAAY,EAAE,CAAA;YAEpB,qEAAqE;YACrE,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC7D,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5D,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACjE,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,UAAU,CAAC,IAAI,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;YAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAmB,CAAA;YAErE,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,EAAE,CAAA;YAE7B,MAAM,gBAAgB,GAAG,KAAK,CAAC;gBAC7B,MAAM,EAAE,GAAG,EAAE;oBACX,aAAa,EAAE,CAAA;oBACf,OAAO,uCAAkB,CAAA;gBAC3B,CAAC;gBACD,aAAa,EAAE,gCAAgC;aAChD,CAAC,CAAA;YAEF,mBAAmB,CAAC;gBAClB,QAAQ;gBACR,WAAW;gBACX,UAAU,EAAE,gBAAC,gBAAgB,OAAG;aACjC,CAAC,CAAA;YACF,MAAM,YAAY,EAAE,CAAA;YAEpB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,gCAAgC,CAAgB,CAAA;YAEvF,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;YAExC,oDAAoD;YACpD,OAAO,CAAC,eAAe,EAAE,CAAA;YACzB,OAAO,CAAC,eAAe,EAAE,CAAA;YACzB,OAAO,CAAC,eAAe,EAAE,CAAA;YAEzB,kDAAkD;YAClD,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAExC,MAAM,YAAY,EAAE,CAAA;YAEpB,uEAAuE;YACvE,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxC,MAAM,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;QAC1C,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/esm/shade.d.ts

@@ -2,25 +2,16 @@ import type { Constructable } from '@furystack/inject';
 import type { ChildrenList, CSSObject, PartialElement, RenderOptions } from './models/index.js';
 export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
     /**
-     * Explicit shadow dom name. Will fall back to 'shade-{guid}' if not provided
+     * The custom element tag name used to register the component.
+     * Must follow the Custom Elements naming convention (lowercase, must contain a hyphen).
+     *
+     * @example 'my-button', 'shade-dialog', 'app-header'
      */
     shadowDomName: string;
     /**
      * Render hook, this method will be executed on each and every render.
      */
     render: (options: RenderOptions<TProps, TElementBase>) => JSX.Element | string | null;
-    /**
-     * Construct hook. Will be executed once when the element has been constructed and initialized
-     */
-    constructed?: (options: RenderOptions<TProps, TElementBase>) => void | undefined | (() => void) | Promise<void | undefined | (() => void)>;
-    /**
-     * Will be executed when the element is attached to the DOM.
-     */
-    onAttach?: (options: RenderOptions<TProps, TElementBase>) => void;
-    /**
-     * Will be executed when the element is detached from the DOM.
-     */
-    onDetach?: (options: RenderOptions<TProps, TElementBase>) => void;
     /**
      * Name of the HTML Element's base class. Needs to be defined if the elementBase is set. E.g.: 'div', 'button', 'input'
      */
@@ -30,18 +21,21 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
      */
     elementBase?: Constructable<TElementBase>;
     /**
-     * A default style that will be applied to the element as inline styles.
-     * Can be overridden by external styles on instances.
+     * Inline styles applied to each component instance.
+     * Use for per-instance dynamic overrides. Prefer `css` for component-level defaults.
      */
     style?: Partial<CSSStyleDeclaration>;
     /**
      * CSS styles injected as a stylesheet during component registration.
-     * Supports pseudo-selectors (&:hover, &:active) and nested selectors (& .class).
-     * Use this for component-level styling that doesn't need per-instance overrides.
+     * Supports pseudo-selectors (`&:hover`, `&:active`) and nested selectors (`& .class`).
+     *
+     * **Best practice:** Prefer `css` over `style` for component defaults -- styles are injected
+     * once per component type (better performance), and support pseudo-selectors and nesting.
      *
      * @example
      * ```typescript
      * css: {
+     *   display: 'flex',
      *   padding: '16px',
      *   '&:hover': { backgroundColor: '#f0f0f0' },
      *   '& .title': { fontWeight: 'bold' }
@@ -56,4 +50,13 @@ export type ShadeOptions<TProps, TElementBase extends HTMLElement> = {
  * @returns the JSX element
  */
 export declare const Shade: <TProps, TElementBase extends HTMLElement = HTMLElement>(o: ShadeOptions<TProps, TElementBase>) => (props: TProps & PartialElement<TElementBase>, children?: ChildrenList) => JSX.Element;
+/**
+ * Flushes any pending microtask-based component updates.
+ * Useful in tests to wait for batched renders to complete before asserting DOM state.
+ *
+ * Note: this flushes one level of pending updates. If a render itself triggers new
+ * `updateComponent()` calls, an additional `await flushUpdates()` may be needed.
+ * @returns a promise that resolves after the current microtask queue has been processed
+ */
+export declare const flushUpdates: () => Promise<void>;
 //# sourceMappingURL=shade.d.ts.map

package/esm/shade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shade.d.ts","sourceRoot":"","sources":["../src/shade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAM/F,MAAM,MAAM,YAAY,CAAC,MAAM,EAAE,YAAY,SAAS,WAAW,IAAI;IACnE;;OAEG;IACH,aAAa,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAErF;;OAEG;IACH,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,KACzC,IAAI,GAAG,SAAS,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAA;IAE/E;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAA;IAEjE;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,IAAI,CAAA;IAEjE;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAEzC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAEpC;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,EAAE,YAAY,SAAS,WAAW,GAAG,WAAW,EAC1E,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,MAiO7B,OAAO,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,EAAE,WAAW,YAAY,KAgB9D,GAAG,CAAC,OAEpB,CAAA"}
+{"version":3,"file":"shade.d.ts","sourceRoot":"","sources":["../src/shade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAS/F,MAAM,MAAM,YAAY,CAAC,MAAM,EAAE,YAAY,SAAS,WAAW,IAAI;IACnE;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAErF;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IAEzC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAA;IAEpC;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,EAAE,YAAY,SAAS,WAAW,GAAG,WAAW,EAC1E,GAAG,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC,MA+V7B,OAAO,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,EAAE,WAAW,YAAY,KAgB9D,GAAG,CAAC,OAEpB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,QAAO,OAAO,CAAC,IAAI,CAA4D,CAAA"}

package/esm/shade.js

@@ -2,15 +2,16 @@ import { hasInjectorReference, Injector } from '@furystack/inject';
 import { ObservableValue } from '@furystack/utils';
 import { LocationService } from './services/location-service.js';
 import { ResourceManager } from './services/resource-manager.js';
-import { attachProps, attachStyles } from './shade-component.js';
+import { attachProps, attachStyles, setRenderMode } from './shade-component.js';
 import { StyleManager } from './style-manager.js';
+import { patchChildren, toVChildArray } from './vnode.js';
 /**
  * Factory method for creating Shade components
  * @param o The options object for component creation
  * @returns the JSX element
  */
 export const Shade = (o) => {
-    // register shadow-dom element
+    // Register custom element
     const customElementName = o.shadowDomName;
     const existing = customElements.get(customElementName);
     if (!existing) {
@@ -28,14 +29,27 @@ export const Shade = (o) => {
                 return this._renderCount;
             }
             resourceManager = new ResourceManager();
+            /**
+             * Host props collected during the current render pass via `useHostProps`.
+             * Applied to the host element after each render.
+             */
+            _pendingHostProps = [];
+            /**
+             * The host props that were applied in the previous render, used for diffing.
+             */
+            _prevHostProps = null;
+            /**
+             * Cached ref objects keyed by the user-provided key string.
+             */
+            _refs = new Map();
             connectedCallback() {
-                o.onAttach?.(this.getRenderOptions());
-                this.callConstructed();
+                this.updateComponent();
             }
             async disconnectedCallback() {
-                o.onDetach?.(this.getRenderOptions());
+                this._refs.clear();
+                this._prevVTree = null;
+                this._prevHostProps = null;
                 await this.resourceManager[Symbol.asyncDispose]();
-                this.cleanup?.();
             }
             /**
              * Will be triggered when updating the external props object
@@ -61,8 +75,18 @@ export const Shade = (o) => {
                     props: this.props,
                     injector: this.injector,
                     children: this.shadeChildren,
-                    element: this,
                     renderCount: this._renderCount,
+                    useHostProps: (hostProps) => {
+                        this._pendingHostProps.push(hostProps);
+                    },
+                    useRef: (key) => {
+                        const existingRef = this._refs.get(key);
+                        if (existingRef)
+                            return existingRef;
+                        const refObject = { current: null };
+                        this._refs.set(key, refObject);
+                        return refObject;
+                    },
                     useObservable: (key, obesrvable, options) => {
                         const onChange = options?.onChange || (() => this.updateComponent());
                         return this.resourceManager.useObservable(key, obesrvable, onChange, options);
@@ -116,43 +140,149 @@ export const Shade = (o) => {
                 };
                 return renderOptions;
             };
+            _updateScheduled = false;
             /**
-             * Updates the component in the DOM.
+             * The VChild array from the previous render, with `_el` references
+             * pointing to the real DOM nodes. Used to diff against the next render.
+             */
+            _prevVTree = null;
+            /**
+             * Schedules a component update via microtask. Multiple calls before the microtask
+             * runs are coalesced into a single render pass.
              */
             updateComponent() {
-                const renderResult = this.render(this.getRenderOptions());
-                if (renderResult === null || renderResult === undefined) {
-                    this.innerHTML = '';
-                }
-                if (typeof renderResult === 'string' || typeof renderResult === 'number') {
-                    this.innerHTML = renderResult;
+                if (!this._updateScheduled) {
+                    this._updateScheduled = true;
+                    queueMicrotask(() => {
+                        this._updateScheduled = false;
+                        this._performUpdate();
+                    });
                 }
-                if (renderResult instanceof HTMLElement) {
-                    this.replaceChildren(renderResult);
+            }
+            _performUpdate() {
+                this._pendingHostProps = [];
+                let renderResult;
+                setRenderMode(true);
+                try {
+                    renderResult = this.render(this.getRenderOptions());
                 }
-                if (renderResult instanceof DocumentFragment) {
-                    this.replaceChildren(renderResult);
+                finally {
+                    setRenderMode(false);
                 }
+                const newVTree = toVChildArray(renderResult);
+                patchChildren(this, this._prevVTree || [], newVTree);
+                this._prevVTree = newVTree;
+                this._applyHostProps();
             }
             /**
-             * Finalize the component initialization after it gets the Props. Called by the framework internally
+             * Merges all pending host props from the render pass and applies them
+             * to the host element, diffing against the previously applied host props.
              */
-            callConstructed() {
-                this.updateComponent();
-                const cleanupResult = o.constructed && o.constructed(this.getRenderOptions());
-                if (cleanupResult instanceof Promise) {
-                    cleanupResult
-                        .then((cleanup) => (this.cleanup = cleanup))
-                        .catch(() => {
-                        /** */
-                    });
+            _applyHostProps() {
+                if (this._pendingHostProps.length === 0) {
+                    if (this._prevHostProps) {
+                        // All host props were removed — clean up
+                        for (const key of Object.keys(this._prevHostProps)) {
+                            if (key === 'style')
+                                continue;
+                            this.removeAttribute(key);
+                        }
+                        if (this._prevHostProps.style) {
+                            for (const sk of Object.keys(this._prevHostProps.style)) {
+                                if (sk.startsWith('--')) {
+                                    this.style.removeProperty(sk);
+                                }
+                                else {
+                                    ;
+                                    this.style[sk] = '';
+                                }
+                            }
+                        }
+                        this._prevHostProps = null;
+                    }
+                    return;
+                }
+                // Merge all pending host prop calls into a single object
+                const merged = {};
+                let mergedStyle;
+                for (const hp of this._pendingHostProps) {
+                    for (const [key, value] of Object.entries(hp)) {
+                        if (key === 'style' && typeof value === 'object' && value !== null) {
+                            mergedStyle = { ...mergedStyle, ...value };
+                        }
+                        else {
+                            merged[key] = value;
+                        }
+                    }
+                }
+                if (mergedStyle) {
+                    merged.style = mergedStyle;
+                }
+                const oldHP = this._prevHostProps || {};
+                const newHP = merged;
+                // Remove attributes no longer present
+                for (const key of Object.keys(oldHP)) {
+                    if (key === 'style')
+                        continue;
+                    if (!(key in newHP)) {
+                        if (key.startsWith('on') && typeof oldHP[key] === 'function') {
+                            ;
+                            this[key] = null;
+                        }
+                        else {
+                            this.removeAttribute(key);
+                        }
+                    }
                 }
-                else {
-                    // construct is not async
-                    this.cleanup = cleanupResult;
+                // Apply new/changed attributes
+                for (const [key, value] of Object.entries(newHP)) {
+                    if (key === 'style')
+                        continue;
+                    if (oldHP[key] !== value) {
+                        if (typeof value === 'function' || (typeof value === 'object' && value !== null)) {
+                            ;
+                            this[key] = value;
+                        }
+                        else if (value === null || value === undefined || value === false) {
+                            if (key in this) {
+                                ;
+                                this[key] = undefined;
+                            }
+                            this.removeAttribute(key);
+                        }
+                        else {
+                            // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                            this.setAttribute(key, String(value));
+                        }
+                    }
+                }
+                // Diff styles
+                const oldStyle = oldHP.style || {};
+                const newStyle = mergedStyle || {};
+                for (const sk of Object.keys(oldStyle)) {
+                    if (!(sk in newStyle)) {
+                        if (sk.startsWith('--')) {
+                            this.style.removeProperty(sk);
+                        }
+                        else {
+                            ;
+                            this.style[sk] = '';
+                        }
+                    }
                 }
+                for (const [sk, sv] of Object.entries(newStyle)) {
+                    if (oldStyle[sk] !== sv) {
+                        if (sk.startsWith('--')) {
+                            this.style.setProperty(sk, sv);
+                        }
+                        else {
+                            ;
+                            this.style[sk] = sv;
+                        }
+                    }
+                }
+                this._prevHostProps = merged;
             }
-            cleanup = undefined;
             _injector;
             getInjectorFromParent() {
                 let parent = this.parentElement;
@@ -185,7 +315,7 @@ export const Shade = (o) => {
         }, o.elementBaseName ? { extends: o.elementBaseName } : undefined);
     }
     else {
-        throw Error(`A custom shade with shadow DOM name '${o.shadowDomName}' has already been registered!`);
+        throw Error(`A custom shade with name '${o.shadowDomName}' has already been registered!`);
     }
     return (props, children) => {
         const ElementType = customElements.get(customElementName);
@@ -202,4 +332,13 @@ export const Shade = (o) => {
         return el;
     };
 };
+/**
+ * Flushes any pending microtask-based component updates.
+ * Useful in tests to wait for batched renders to complete before asserting DOM state.
+ *
+ * Note: this flushes one level of pending updates. If a render itself triggers new
+ * `updateComponent()` calls, an additional `await flushUpdates()` may be needed.
+ * @returns a promise that resolves after the current microtask queue has been processed
+ */
+export const flushUpdates = () => new Promise((resolve) => queueMicrotask(resolve));
 //# sourceMappingURL=shade.js.map