From 1b49e44a0678a6b51bbf3875ef9cfe43cb01da6d Mon Sep 17 00:00:00 2001 From: Omri SirComp Date: Wed, 20 May 2026 20:32:24 +0300 Subject: [PATCH] fix: document named motion easings --- packages/interact/docs/api/types.md | 4 ++-- packages/interact/src/types/config.ts | 5 +++-- packages/interact/src/types/effects.ts | 7 ++++--- packages/motion/README.md | 13 +++++++++++++ packages/motion/docs/api/README.md | 7 +++++-- packages/motion/docs/api/types.md | 18 ++++++++++++++++-- packages/motion/src/easings.ts | 6 ++++++ packages/motion/src/types.ts | 8 +++++--- packages/motion/src/utils.ts | 7 +++---- 9 files changed, 57 insertions(+), 18 deletions(-) diff --git a/packages/interact/docs/api/types.md b/packages/interact/docs/api/types.md index ba342652..073f6f51 100644 --- a/packages/interact/docs/api/types.md +++ b/packages/interact/docs/api/types.md @@ -453,7 +453,7 @@ type TimeEffect = { selector?: string; listContainer?: string; duration: number; - easing?: string; + easing?: CssEasing; iterations?: number; alternate?: boolean; fill?: Fill; @@ -534,7 +534,7 @@ type ScrubEffect = { key?: string; selector?: string; listContainer?: string; - easing?: string; + easing?: CssEasing; iterations?: number; alternate?: boolean; fill?: Fill; diff --git a/packages/interact/src/types/config.ts b/packages/interact/src/types/config.ts index a2d3f71d..6dedcf4e 100644 --- a/packages/interact/src/types/config.ts +++ b/packages/interact/src/types/config.ts @@ -1,3 +1,4 @@ +import type { JsEasing } from '@wix/motion'; import type { TriggerType, TriggerParams } from './triggers'; import type { Effect, EffectRef, EffectProperty, TimeAnimationTriggerType } from './effects'; @@ -9,7 +10,7 @@ export type Condition = { export type SequenceOptionsConfig = { delay?: number; offset?: number; - offsetEasing?: string | ((p: number) => number); + offsetEasing?: JsEasing | ((p: number) => number); sequenceId?: string; conditions?: string[]; triggerType?: TimeAnimationTriggerType; @@ -24,7 +25,7 @@ export type SequenceConfigRef = { } & { delay?: number; offset?: number; - offsetEasing?: string | ((p: number) => number); + offsetEasing?: JsEasing | ((p: number) => number); conditions?: string[]; }; diff --git a/packages/interact/src/types/effects.ts b/packages/interact/src/types/effects.ts index 43dd3d21..866cbd08 100644 --- a/packages/interact/src/types/effects.ts +++ b/packages/interact/src/types/effects.ts @@ -3,6 +3,7 @@ import type { RangeOffset, ScrubTransitionEasing, MotionAnimationOptions, + CssEasing, } from '@wix/motion'; type Fill = 'none' | 'forwards' | 'backwards' | 'both'; @@ -29,7 +30,7 @@ type EffectEffectProperty = export type TimeEffect = { duration: number; - easing?: string; + easing?: CssEasing; iterations?: number; alternate?: boolean; fill?: Fill; @@ -40,7 +41,7 @@ export type TimeEffect = { } & EffectEffectProperty; export type ScrubEffect = { - easing?: string; + easing?: CssEasing; iterations?: number; alternate?: boolean; fill?: Fill; @@ -57,7 +58,7 @@ export type ScrubEffect = { export type TransitionOptions = { duration?: number; delay?: number; - easing?: string; + easing?: CssEasing; }; export type StyleProperty = { diff --git a/packages/motion/README.md b/packages/motion/README.md index 858c5df6..dc1ab158 100644 --- a/packages/motion/README.md +++ b/packages/motion/README.md @@ -37,6 +37,19 @@ const animation = getWebAnimation(document.getElementById('myElement'), { await animation.play(); ``` +### Named Easings + +`@wix/motion` exports the `cssEasings` map for reusable CSS easing strings, plus `CssEasingName` and `CssEasing` types for typed pickers and animation config. + +```typescript +import { cssEasings, type CssEasingName } from '@wix/motion'; + +const easingName: CssEasingName = 'sineInOut'; +const easing = cssEasings[easingName]; +``` + +Available names: `linear`, `ease`, `easeIn`, `easeOut`, `easeInOut`, `sineIn`, `sineOut`, `sineInOut`, `quadIn`, `quadOut`, `quadInOut`, `cubicIn`, `cubicOut`, `cubicInOut`, `quartIn`, `quartOut`, `quartInOut`, `quintIn`, `quintOut`, `quintInOut`, `expoIn`, `expoOut`, `expoInOut`, `circIn`, `circOut`, `circInOut`, `backIn`, `backOut`, `backInOut`. + ### Scroll-Driven Animation ```typescript diff --git a/packages/motion/docs/api/README.md b/packages/motion/docs/api/README.md index aba88734..0a27174f 100644 --- a/packages/motion/docs/api/README.md +++ b/packages/motion/docs/api/README.md @@ -40,7 +40,7 @@ Complete reference for all Wix Motion functions, types, and classes. ### Basic Animation Creation ```typescript -import { getWebAnimation } from '@wix/motion'; +import { getWebAnimation, cssEasings, type CssEasingName } from '@wix/motion'; const animation = getWebAnimation( element, // HTMLElement | string | null @@ -48,6 +48,9 @@ const animation = getWebAnimation( trigger?, // TriggerVariant (for scroll/mouse) options? // Record ); + +const easingName: CssEasingName = 'sineInOut'; +const easingValue = cssEasings[easingName]; ``` ### Scroll Scene Creation @@ -115,7 +118,7 @@ interface TimeAnimationOptions { customEffect?: CustomEffect; duration?: number; delay?: number; - easing?: string; + easing?: CssEasing; iterations?: number; // ... more properties } diff --git a/packages/motion/docs/api/types.md b/packages/motion/docs/api/types.md index 9d1bb0c5..11afc678 100644 --- a/packages/motion/docs/api/types.md +++ b/packages/motion/docs/api/types.md @@ -12,6 +12,20 @@ Wix Motion provides comprehensive TypeScript support with detailed type definiti - **Utility Types** - Measurements, directions, and helper types - **Advanced Types** - Custom effects and trigger configurations +## Named Easing Types + +`@wix/motion` exports `cssEasings`, a map of public CSS easing names to their CSS values. Use `CssEasingName` when you need the exact named key set, such as for dropdowns, autocomplete, or persisted config validation. + +```typescript +import { cssEasings, type CssEasingName, type CssEasing } from '@wix/motion'; + +const name: CssEasingName = 'quadOut'; +const cssValue = cssEasings[name]; +const option: CssEasing = 'cubic-bezier(0.25, 0.46, 0.45, 0.94)'; +``` + +Available `CssEasingName` values: `linear`, `ease`, `easeIn`, `easeOut`, `easeInOut`, `sineIn`, `sineOut`, `sineInOut`, `quadIn`, `quadOut`, `quadInOut`, `cubicIn`, `cubicOut`, `cubicInOut`, `quartIn`, `quartOut`, `quartInOut`, `quintIn`, `quintOut`, `quintInOut`, `expoIn`, `expoOut`, `expoInOut`, `circIn`, `circOut`, `circInOut`, `backIn`, `backOut`, `backInOut`. + ## Core Configuration Types ### `TimeAnimationOptions` @@ -27,7 +41,7 @@ interface TimeAnimationOptions { duration?: number; // Milliseconds delay?: number; // Milliseconds endDelay?: number; // Milliseconds - easing?: string; // CSS or JS easing function + easing?: CssEasing; // Named easing from cssEasings, or any CSS easing string iterations?: number; // Number of repeats (Infinity or 0 for infinite) alternate?: boolean; // Alternating effect direction on each iteration fill?: AnimationFillMode; // 'none' | 'backwards' | 'forwards' | 'both' @@ -86,7 +100,7 @@ interface ScrubAnimationOptions { startOffset?: RangeOffset; // animation-range-start for usage with view() timelines endOffset?: RangeOffset; // animation-range-end for usage with view() timelines playbackRate?: number; // Speed multiplier - easing?: string; // Transition easing + easing?: CssEasing; // Named easing from cssEasings, or any CSS easing string iterations?: number; // Usually 1 for scrub animations fill?: AnimationFillMode; alternate?: boolean; diff --git a/packages/motion/src/easings.ts b/packages/motion/src/easings.ts index 378ab3fe..7ab56657 100644 --- a/packages/motion/src/easings.ts +++ b/packages/motion/src/easings.ts @@ -212,6 +212,9 @@ export const jsEasings = { backInOut, }; +export type JsEasingName = keyof typeof jsEasings; +export type JsEasing = JsEasingName | (string & {}); + /** * CSS cubic-bezier easings based on PostCSS Easings */ @@ -246,3 +249,6 @@ export const cssEasings = { backOut: 'cubic-bezier(0.175, 0.885, 0.32, 1.275)', backInOut: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)', } as const; + +export type CssEasingName = keyof typeof cssEasings; +export type CssEasing = CssEasingName | (string & {}); diff --git a/packages/motion/src/types.ts b/packages/motion/src/types.ts index 97c82db3..b99d2d12 100644 --- a/packages/motion/src/types.ts +++ b/packages/motion/src/types.ts @@ -1,3 +1,5 @@ +import type { CssEasing, JsEasing } from './easings'; + type LengthUnit = 'px' | 'em' | 'rem' | 'vh' | 'vw' | 'vmin' | 'vmax'; export declare type Length = { @@ -148,7 +150,7 @@ export type TimeAnimationOptions duration?: number; delay?: number; endDelay?: number; - easing?: string; + easing?: CssEasing; iterations?: number; alternate?: boolean; fill?: AnimationFillMode; @@ -165,7 +167,7 @@ type ScrubAnimationDataBase = { startOffset?: RangeOffset; endOffset?: RangeOffset; playbackRate?: number; - easing?: string; + easing?: CssEasing; iterations?: number; fill?: AnimationFillMode; alternate?: boolean; @@ -268,7 +270,7 @@ export type EffectModule = export type SequenceOptions = { delay?: number; offset?: number; - offsetEasing?: string | ((p: number) => number); + offsetEasing?: JsEasing | ((p: number) => number); }; export type AnimationGroupArgs = { diff --git a/packages/motion/src/utils.ts b/packages/motion/src/utils.ts index ab6dd036..da074831 100644 --- a/packages/motion/src/utils.ts +++ b/packages/motion/src/utils.ts @@ -1,10 +1,11 @@ import { cssEasings, jsEasings } from './easings'; +import type { CssEasing, JsEasing } from './easings'; export function getCssUnits(unit: 'percentage' | string) { return unit === 'percentage' ? '%' : unit || 'px'; } -export function getEasing(easing?: keyof typeof cssEasings | string): string { +export function getEasing(easing?: CssEasing): string { return easing ? cssEasings[easing as keyof typeof cssEasings] || easing : cssEasings.linear; } @@ -174,9 +175,7 @@ function parseCssLinear(str: string): ((t: number) => number) | undefined { }; } -export function getJsEasing( - easing?: keyof typeof jsEasings | string, -): ((t: number) => number) | undefined { +export function getJsEasing(easing?: JsEasing): ((t: number) => number) | undefined { if (!easing) return undefined; const named = jsEasings[easing as keyof typeof jsEasings];