humanspeak / svelte-motion / 28118006750

57%

main: 57%

push

github

feat(motion-values): add useWillChange hook (#327) (#419)

* feat(motion-values): add useWillChange hook (#327)

Add useWillChange, a Framer Motion-compatible hook returning a MotionValue
for style.willChange. It starts at "auto" and latches to "transform" the
first time a transform or accelerated property animates on the element it's
attached to — promoting the element to its own compositor layer only while
it actually needs one. The latch is one-way, matching upstream.

- src/lib/utils/willChange.svelte.ts: useWillChange + WillChangeMotionValue
  (+ isWillChangeMotionValue guard); exported from index.
- _MotionContainer: notifyWillChange wires the declarative animate path so
  animating x/opacity/etc. flips the attached will-change value.
- Demo: src/routes/tests/will-change (transform box flips, color box stays
  auto), linked from the test index.
- Docs: /docs/use-will-change page + /examples/use-will-change with a
  reusable Default demo; nav entry added.
- Tests: unit coverage for the latch + type guard; Playwright e2e asserting
  the flip, the one-way latch on return, and that non-transform animations
  never promote.

Closes #327

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(motion-values): cover controls path and clarify latch in useWillChange

Address CodeRabbit review on the useWillChange feature:

- _MotionContainer: notify will-change from the imperative controls path
  (useAnimationControls/useAnimate) too, so controls.start({ x }) promotes
  the element instead of leaving will-change at "auto". Mirrors the
  declarative animate seam. Gestures remain the only deferred path.
- Docs/examples: correct wording that implied the hint is active only while
  animating — it is a one-way latch (auto → transform, then stays).
- willChange.svelte.ts: add the required @example to isWillChangeMotionValue.
- e2e: add the controls-path test, a keyboard-activation (Enter) test, and a
  repeated non-transform toggle assertio... (continued)

769 of 1571 branches covered (48.95%)

Branch coverage included in aggregate %.

17 of 18 new or added lines in 2 files covered. (94.44%)

3014 of 5036 relevant lines covered (59.85%)

15.17 hits per line