Merge pull request #3162 from motiondivision/feature/immediate-on-change

`styleEffect`

Author: mattgperry

.cursorrules

@@ -0,0 +1,11 @@
+## Writing tests
+
+-  When waiting for the next frame, use an `async` test and await like so:
+
+```javascript
+async function nextFrame() {
+    return new Promise<void>((resolve) => {
+        frame.postRender(() => resolve())
+    })
+}
+```

CHANGELOG.md

@@ -4,6 +4,12 @@ Motion adheres to [Semantic Versioning](http://semver.org/).
 
 Undocumented APIs should be considered internal and may change without warning.
 
+## [12.9.0] 2025-04-23
+
+### Added
+
+-   `styleEffect`
+
 ## [12.8.3] 2025-04-24
 
 ### Changed
@@ -20,13 +26,13 @@ Undocumented APIs should be considered internal and may change without warning.
 
 -   Unifying `transform` behaviour for SVG and CSS switched from element measurements for `transform-box: fill-box`.
 
-## [12.8.1] 2025-04-22
+## [12.8.1] 2025-04-23
 
 ### Fixed
 
 -   Removing errant `console.trace` on `value.set("none")`.
 
-## [12.8.0] 2025-04-22
+## [12.8.0] 2025-04-23
 
 ### Added
 

packages/motion-dom/src/effects/__tests__/style-effect.test.ts

@@ -0,0 +1,180 @@
+import { frame } from "../../frameloop"
+import { motionValue } from "../../value"
+import { styleEffect } from "../style-effect"
+
+async function nextFrame() {
+    return new Promise<void>((resolve) => {
+        frame.postRender(() => resolve())
+    })
+}
+
+describe("styleEffect", () => {
+    it("sets styles after styleEffect is applied", async () => {
+        const element = document.createElement("div")
+
+        // Create motion values
+        const width = motionValue("100px")
+        const color = motionValue("red")
+
+        // Apply style effect
+        styleEffect(element, {
+            width,
+            color,
+        })
+
+        await nextFrame()
+
+        // Verify styles are set
+        expect(element.style.width).toBe("100px")
+        expect(element.style.color).toBe("red")
+    })
+
+    it("updates styles when motion values change", async () => {
+        const element = document.createElement("div")
+        // Create motion values
+        const width = motionValue("100px")
+        const color = motionValue("red")
+
+        // Apply style effect
+        styleEffect(element, {
+            width,
+            color,
+        })
+
+        await nextFrame()
+
+        // Verify initial styles
+        expect(element.style.width).toBe("100px")
+        expect(element.style.color).toBe("red")
+
+        // Change motion values
+        width.set("200px")
+        color.set("blue")
+
+        // Updates should be scheduled for the next frame render
+        // Styles should not have changed yet
+        expect(element.style.width).toBe("100px")
+        expect(element.style.color).toBe("red")
+
+        await nextFrame()
+
+        // Verify styles are updated
+        expect(element.style.width).toBe("200px")
+        expect(element.style.color).toBe("blue")
+    })
+
+    it("handles multiple elements", async () => {
+        // Create additional elements
+        const element = document.createElement("div")
+        const element2 = document.createElement("div")
+
+        const margin = motionValue("10px")
+        const backgroundColor = motionValue("yellow")
+
+        styleEffect([element, element2], {
+            margin,
+            backgroundColor,
+        })
+
+        await nextFrame()
+
+        expect(element.style.margin).toBe("10px")
+        expect(element.style.backgroundColor).toBe("yellow")
+        expect(element2.style.margin).toBe("10px")
+        expect(element2.style.backgroundColor).toBe("yellow")
+
+        margin.set("20px")
+        backgroundColor.set("green")
+
+        await nextFrame()
+
+        expect(element.style.margin).toBe("20px")
+        expect(element.style.backgroundColor).toBe("green")
+    })
+
+    it("returns cleanup function that stops updating styles", async () => {
+        const element = document.createElement("div")
+        // Create motion values
+        const padding = motionValue("5px")
+        const opacity = motionValue("0.5")
+
+        // Apply style effect and get cleanup function
+        const cleanup = styleEffect(element, {
+            padding,
+            opacity,
+        })
+
+        await nextFrame()
+
+        // Verify initial styles
+        expect(element.style.padding).toBe("5px")
+        expect(element.style.opacity).toBe("0.5")
+
+        // Change values and verify update on next frame
+        padding.set("10px")
+        opacity.set("0.8")
+
+        await nextFrame()
+
+        // Verify update happened
+        expect(element.style.padding).toBe("10px")
+        expect(element.style.opacity).toBe("0.8")
+
+        // Call cleanup function
+        cleanup()
+
+        // Change values again
+        padding.set("15px")
+        opacity.set("1")
+
+        await nextFrame()
+
+        // Verify styles didn't change after cleanup
+        expect(element.style.padding).toBe("10px")
+        expect(element.style.opacity).toBe("0.8")
+    })
+
+    it("returns cleanup function that stops updating styles that have already been scheduled", async () => {
+        const element = document.createElement("div")
+
+        // Create motion values
+        const padding = motionValue("5px")
+        const opacity = motionValue("0.5")
+
+        // Apply style effect and get cleanup function
+        const cleanup = styleEffect(element, {
+            padding,
+            opacity,
+        })
+
+        await nextFrame()
+
+        // Verify initial styles
+        expect(element.style.padding).toBe("5px")
+        expect(element.style.opacity).toBe("0.5")
+
+        // Change values and verify update on next frame
+        padding.set("10px")
+        opacity.set("0.8")
+
+        await nextFrame()
+
+        // Verify update happened
+        expect(element.style.padding).toBe("10px")
+        expect(element.style.opacity).toBe("0.8")
+
+        // Change values again
+        padding.set("15px")
+        opacity.set("1")
+
+        // Call cleanup function
+        cleanup()
+
+        // Check that values don't update on the next frame
+        await nextFrame()
+
+        // Verify styles didn't change after cleanup
+        expect(element.style.padding).toBe("10px")
+        expect(element.style.opacity).toBe("0.8")
+    })
+})

packages/motion-dom/src/effects/style-effect.ts

@@ -0,0 +1,46 @@
+import { cancelFrame, frame } from "../frameloop"
+import { ElementOrSelector, resolveElements } from "../utils/resolve-elements"
+import { MotionValue } from "../value"
+
+export function styleEffect(
+    subject: ElementOrSelector,
+    values: Record<string, MotionValue>
+) {
+    const elements = resolveElements(subject) as HTMLElement[]
+    const subscriptions: VoidFunction[] = []
+
+    for (let i = 0; i < elements.length; i++) {
+        const element = elements[i]
+
+        for (const key in values) {
+            const value = values[key]
+
+            /**
+             * TODO: Get specific setters for combined props (like x)
+             * or values with default types (like color)
+             *
+             * TODO: CSS variable support
+             */
+            const updateStyle = () => {
+                element.style[key as any] = value.get()
+            }
+
+            const scheduleUpdate = () => frame.render(updateStyle)
+
+            const cancel = value.on("change", scheduleUpdate)
+
+            scheduleUpdate()
+
+            subscriptions.push(() => {
+                cancel()
+                cancelFrame(updateStyle)
+            })
+        }
+    }
+
+    return () => {
+        for (const cancel of subscriptions) {
+            cancel()
+        }
+    }
+}

packages/motion-dom/src/index.ts

@@ -36,6 +36,8 @@ export * from "./animation/waapi/supports/waapi"
 export * from "./animation/waapi/utils/accelerated-values"
 export * from "./animation/waapi/utils/linear"
 
+export * from "./effects/style-effect"
+
 export * from "./frameloop"
 export * from "./frameloop/batcher"
 export * from "./frameloop/microtask"

packages/motion-dom/src/value/index.ts

@@ -320,13 +320,13 @@ export class MotionValue<V = any> {
         this.setCurrent(v)
 
         // Update update subscribers
-        if (this.current !== this.prev && this.events.change) {
-            this.events.change.notify(this.current)
+        if (this.current !== this.prev) {
+            this.events.change?.notify(this.current)
         }
 
         // Update render subscribers
-        if (render && this.events.renderRequest) {
-            this.events.renderRequest.notify(this.current)
+        if (render) {
+            this.events.renderRequest?.notify(this.current)
         }
     }