feat(motion): add interpolate and mapRange helper

[realtushartyagi]

Description

Adds mapRange and interpolate helpers to @termuijs/motion for mapping values between numeric ranges, with support for clamping, extrapolation, descending ranges, and safe handling of zero-width input ranges.

Related Issue

Closes #493

Which package(s)?

@termuijs/motion

Type of Change

• 🐛 Bug fix (type:bug)
• ✨ Feature (type:feature)
• 📝 Docs (type:docs)
• 🧪 Tests (type:testing)
• ♻️ Refactor (type:refactor)
• 🎨 Design / UX (type:design)
• ♿ Accessibility (type:accessibility)
• ⚡ Performance (type:performance)
• 🔧 DevOps / CI (type:devops)
• 🔒 Security (type:security)

Checklist

• ⭐ You starred the repo. The needs-star check blocks your merge otherwise.
• Tests pass locally: bun vitest run
• Build passes: bun run build
• Typecheck passes: bun run typecheck
• You read CONTRIBUTING.md.
• Your PR title follows type: short description.
• Widget state mutators call markDirty() (if your change affects rendering).
• No new any types without an inline comment explaining why.
• No unrelated refactors bundled into this PR.

GSSoC 2026 Participation

• You are a GSSoC 2026 contributor.
• Your GSSoC profile: https://gssoc.girlscript.org/profile/f49aa65e-aab2-4e9f-99d6-2174f339ecfe

Screenshots / Recordings (UI changes)

(N/A - Pure mathematical utility functions with no UI)

Notes for the Reviewer

• Added tests for range mapping, clamping, extrapolation, descending ranges, and zero-width inputs.
• Verified interpolate delegates to mapRange.
• Functions are pure and immutable.

Summary by CodeRabbit

• New Features

  • Added numeric interpolation utilities to the motion package for mapping and transforming values between ranges with optional clamping support.

• Tests

  • Added comprehensive test coverage for interpolation utilities, including edge cases and clamping behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4943610e-7192-4c19-9fad-b1b1d390a7b8

📥 Commits

Reviewing files that changed from the base of the PR and between c36cc8c and a6f6d6d.

📒 Files selected for processing (3)

• packages/motion/src/index.ts
• packages/motion/src/interpolate.test.ts
• packages/motion/src/interpolate.ts

---

📝 Walkthrough

Walkthrough

This PR adds numeric interpolation utilities to the @termuijs/motion package. The implementation introduces mapRange to transform values between numeric ranges and interpolate as a tuple-based convenience wrapper, both with optional clamping behavior. Tests validate midpoint mapping, default clamping, unclamped extrapolation, zero-width input handling, and descending output ranges.

Changes

Interpolation Helpers

Layer / File(s)	Summary
Core interpolation implementation packages/motion/src/interpolate.ts	InterpolateOptions with optional clamp flag, mapRange transforms values between input/output numeric ranges with optional clamping and zero-width guards, interpolate delegates to mapRange using tuple ranges.
Test coverage packages/motion/src/interpolate.test.ts	Vitest suite covering midpoint mapping, default clamping behavior, unclamped extrapolation with clamp: false, zero-width input ranges, descending ranges, and tuple-based interpolation.
Public API export packages/motion/src/index.ts	Package entry point re-exports mapRange, interpolate, and InterpolateOptions type.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

type:feature, type:testing, area:motion, level:beginner

Suggested reviewers

• Karanjot786

Poem

🐰 From zero to one, the ranges align,
Mapping each value through numbers divine.
Clamp or extrapolate, the choice is yours true,
Now every motion can interpolate too! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(motion): add interpolate and mapRange helper' directly and concisely summarizes the main change—adding two new helper functions to the motion package.
Description check	✅ Passed	The description covers all required template sections: clear problem statement, linked issue, affected package, type of change, completed checklist, and GSSoC participation with reviewer notes.
Linked Issues check	✅ Passed	The PR fully implements all requirements from issue #493: mapRange and interpolate functions with correct signatures, clamping support, zero-width input handling, descending range support, and comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are confined to packages/motion as required: new interpolate.ts implementation, interpolate.test.ts with comprehensive tests, and index.ts exports only. No modifications to other packages or unrelated code.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds numeric interpolation utilities to @termuijs/motion, including a low-level range mapper and a tuple-based convenience wrapper, and exposes them via the package entrypoint with accompanying Vitest coverage.

Changes:

• Added mapRange and interpolate helpers with optional clamping behavior.
• Added Vitest tests covering default clamping, extrapolation, descending output ranges, and zero-width input ranges.
• Exported the new helpers and option type from packages/motion/src/index.ts.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/motion/src/interpolate.ts	Introduces mapRange and interpolate implementations and option type.
packages/motion/src/interpolate.test.ts	Adds unit tests validating interpolation behavior and clamping.
packages/motion/src/index.ts	Re-exports the new helpers/types from the package entrypoint.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.