npm - @motion.page/sdk - Versions diffs - 1.0.1 → 1.0.3 - Mend

@motion.page/sdk 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +69 -6
package/dist/core/Timeline.d.ts +66 -5
package/dist/easing/index.d.ts +44 -1
package/dist/index.cjs +5 -7
package/dist/index.cjs.map +16 -16
package/dist/index.js +5 -7
package/dist/index.js.map +16 -16
package/dist/triggers/CursorTrigger.d.ts +2 -2
package/dist/triggers/EventTrigger.d.ts +4 -0
package/dist/triggers/GlobalScrollListener.d.ts +36 -0
package/dist/triggers/MarkerManager.d.ts +15 -1
package/dist/triggers/PinManager.d.ts +42 -0
package/dist/triggers/TriggerManager.d.ts +2 -0
package/dist/types/index.d.ts +23 -0
package/dist/utils/FilterParser.d.ts +7 -1
package/dist/utils/TextSplitter.d.ts +5 -0
package/dist/utils/getLayoutRect.d.ts +6 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -636,7 +636,7 @@ Motion('parallax-depth', '.layer', {
 }).onMouseMove({ type: 'axis', smooth: 0.1 });
 ```
-#### `.onPageLoad()`
+#### `.onPageLoad(config?)`
 Play the animation automatically when the page finishes loading. If called after `DOMContentLoaded` has already fired (common in SPAs or scripts placed at the bottom of `<body>`), the animation plays immediately.
@@ -647,6 +647,24 @@ Motion('page-intro', [
 ]).onPageLoad();
 ```
+**`paused` option** — build the timeline (applies initial states) but don't auto-play. Start it manually with `Motion(name).play()`:
+```ts
+// Load timeline paused — user triggers manually
+Motion('hero', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 1 })
+  .onPageLoad({ paused: true })
+// Later, trigger manually:
+Motion('hero').play()
+```
+Can combine with `timing`:
+```ts
+Motion('hero', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 1 })
+  .onPageLoad({ timing: 'after', paused: true })
+```
 #### `.onPageExit(config?)`
 Intercept link clicks, play the exit animation, then navigate to the destination URL after the timeline completes. Works on any website with no server-side dependencies.
@@ -770,7 +788,6 @@ Replace the native cursor with a fully animated custom cursor.
 ```ts
 interface CursorConfig {
-  target?: string | Element;
   type?: 'basic' | 'text' | 'media';
   smooth?: number;
   squeeze?: boolean | { min?: number; max?: number; multiplier?: number };
@@ -800,7 +817,6 @@ Motion('custom-cursor', 'body', {
   to: { opacity: 1 },
   duration: 0,
 }).onCursor({
-  target: '#cursor-dot',
   smooth: 0.08,
   hideNative: true,
   default: { width: 12, height: 12, borderRadius: '50%', backgroundColor: '#fff' },
@@ -818,7 +834,6 @@ Motion('custom-cursor', 'body', {
 ```ts
 Motion('cursor', 'body', { to: { opacity: 1 }, duration: 0 }).onCursor({
-  target: '#cursor',
   type: 'text',
   hideNative: true,
   default: { width: 12, height: 12, borderRadius: '50%', backgroundColor: '#fff' },
@@ -836,7 +851,6 @@ Motion('cursor', 'body', { to: { opacity: 1 }, duration: 0 }).onCursor({
 ```ts
 Motion('cursor', 'body', { to: { opacity: 1 }, duration: 0 }).onCursor({
-  target: '#cursor',
   type: 'media',
   hideNative: true,
   default: { width: 48, height: 48, borderRadius: '50%' },
@@ -885,7 +899,7 @@ Motion('slide-in', '.card', { from: { opacity: 0 }, duration: 0.6 })
 | Start | `.onStart(cb)` | `onStart` | none |
 | Update | `.onUpdate(cb)` | `onUpdate` | `(progress: number, time: number)` via method; `(progress: number)` via config |
 | Complete | `.onComplete(cb)` | `onComplete` | none |
-| Repeat | — | `onRepeat` | `(repeatCount: number)` |
+| Repeat | `.onRepeat(cb)` | `onRepeat` | `(repeatCount: number)` |
 | Reverse complete | — | `onReverseComplete` | none |
 ---
@@ -1055,6 +1069,55 @@ repeat: { times: -1, yoyo: true, delay: 0.2 }  // infinite yoyo with pause betwe
 repeat: { times: 2, yoyo: true, delay: 0.5 }   // 2 extra cycles, yoyo, 0.5s pause
 ```
+### Timeline Repeat
+`.withRepeat()` loops the **entire timeline** after all its animations complete — distinct from per-animation `repeat` in `AnimationConfig`, which only loops an individual animation within the timeline.
+```ts
+// Shorthand — loop count (-1 = infinite, 0 = no extra loops)
+tl.withRepeat(-1): this
+// Full config
+tl.withRepeat(config: TimelineRepeatConfig): this
+interface TimelineRepeatConfig {
+  times:  number;   // Number of additional repetitions (-1 = infinite)
+  yoyo?:  boolean;  // Alternate direction each cycle
+  delay?: number;   // Seconds between timeline repetitions
+}
+```
+```ts
+// Loop the entire timeline infinitely
+Motion('hero', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 1 })
+  .withRepeat(-1)
+  .onPageLoad()
+// Loop 3 times with yoyo and delay
+Motion('bounce', [
+  { target: '.a', from: { y: '100%' }, to: { y: '0%' }, duration: 0.5 },
+  { target: '.b', from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.3, position: 0.2 }
+])
+  .withRepeat({ times: 3, yoyo: true, delay: 0.5 })
+  .onPageLoad()
+```
+Use `.onRepeat()` on the `Timeline` instance to react to each completed cycle:
+```ts
+Motion('loop', '.el', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.8 })
+  .withRepeat(-1)
+  .onRepeat((count) => console.log(`Cycle ${count} complete`))
+  .onPageLoad()
+```
+**Per-animation vs. timeline repeat:**
+| Scope | API | Effect |
+|-------|-----|--------|
+| Individual animation | `repeat` in `AnimationConfig` | Loops just that one animation within the timeline |
+| Entire timeline | `.withRepeat()` on `Timeline` | Loops all animations in the timeline together |
 ### SplitType
 ```ts

package/dist/core/Timeline.d.ts CHANGED Viewed

@@ -9,7 +9,7 @@
  * - Control methods (play, pause, reverse, seek, etc.)
  * - Trigger system integration
  */
-import type { HoverConfig, ClickConfig, ScrollConfig, MouseMoveConfig, GestureConfig, CursorConfig, PageExitConfig, TargetInput, AnimationConfig } from '../types';
+import type { HoverConfig, ClickConfig, ScrollConfig, MouseMoveConfig, GestureConfig, CursorConfig, PageExitConfig, TargetInput, AnimationConfig, TimelineConfig, RepeatConfig } from '../types';
 import { Animation } from './Animation';
 export declare class Timeline {
     /** Monotonic counter for generating unique each-mode instance names */
@@ -34,9 +34,18 @@ export declare class Timeline {
     private _isActive;
     private _isReversed;
     private _killed;
+    private _atZeroState;
+    private _repeat;
+    private _repeatDelay;
+    private _yoyo;
+    private _currentRepeat;
+    private _completeFired;
+    private _inRepeatDelay;
+    private _repeatDelayCounter;
     private _onStart?;
     private _onUpdate?;
     private _onComplete?;
+    private _onRepeat?;
     private _startFired;
     /**
      * Reference to attached trigger (for cleanup in kill()).
@@ -62,11 +71,17 @@ export declare class Timeline {
     private _savedTransitions;
     private _transitionsDisabled;
     private _savedWillChange;
-    constructor(name?: string);
+    private _willChangeApplied;
+    constructor(name?: string, config?: TimelineConfig);
     /**
-     * Get timeline duration
+     * Get timeline duration (single cycle)
      */
     duration(): number;
+    /**
+     * Get total duration including all repeats.
+     * Returns Infinity when repeat is -1 (infinite loop).
+     */
+    totalDuration(): number;
     /**
      * Clear timeline state for rebuild (used for re-triggerable animations)
      * Kills existing animations, clears children, resets state
@@ -86,6 +101,12 @@ export declare class Timeline {
      * from fighting frame-by-frame SDK rendering.
      */
     private _disableTransitions;
+    /**
+     * Apply will-change: transform to elements with transform animations.
+     * Deferred from build time to first tick so the browser has at least one
+     * frame to layout newly-created elements (e.g. text split spans).
+     */
+    private _applyWillChange;
     /**
      * Restore original CSS transition values on all animated elements.
      * Called on timeline completion and kill to re-enable CSS hover/focus
@@ -174,9 +195,17 @@ export declare class Timeline {
      */
     private _setupMouseMoveEachMode;
     /**
-     * Trigger timeline on page load
+     * Trigger timeline on page load.
+     *
+     * @param config - Optional configuration
+     * @param config.timing - When to play: 'before' (immediately), 'during' (DOMContentLoaded), 'after' (window load). Defaults to 'during'.
+     * @param config.paused - When true, the timeline is built but NOT played automatically.
+     *   Start it manually with `Motion('timelineName').play()`.
      */
-    onPageLoad(): this;
+    onPageLoad(config?: {
+        timing?: 'before' | 'during' | 'after';
+        paused?: boolean;
+    }): this;
     /**
      * Trigger timeline when user navigates away from the page (clicks a link).
      * Intercepts the click, plays the exit animation, then navigates to the target URL.
@@ -215,6 +244,8 @@ export declare class Timeline {
     /**
      * Play timeline from position.
      * If already playing forward, continues from current position.
+     * No-op if already completed forward (at the end) and no `from` is specified —
+     * prevents spurious onStart/onComplete re-firing during continuous gesture events.
      */
     play(from?: number): this;
     /**
@@ -224,12 +255,20 @@ export declare class Timeline {
     /**
      * Reverse timeline from position.
      * If already reversing, continues from current position.
+     * No-op if already completed reverse (at the start) and no `from` is specified —
+     * prevents spurious onStart/onComplete re-firing during continuous gesture events.
      */
     reverse(from?: number): this;
     /**
      * Restart timeline
      */
     restart(): this;
+    /**
+     * Reset all children for the start of a new repeat cycle.
+     * Restores elements to their captured initial values and re-renders
+     * position-0 animations at their FROM state.
+     */
+    private _resetChildrenForCycle;
     /**
      * Render only position-0 (non-lazy) animations at their start state
      */
@@ -258,6 +297,24 @@ export declare class Timeline {
      * Set callback for when timeline completes
      */
     onComplete(callback: () => void): this;
+    /**
+     * Set callback for each repeat cycle completion
+     * @param callback - Receives the current repeat count (starts at 1)
+     */
+    onRepeat(callback: (repeatCount: number) => void): this;
+    /**
+     * Configure timeline-level repeat behavior (fluent).
+     * Use -1 for infinite repeat, or a RepeatConfig for advanced options.
+     * @example
+     * Motion('loop', '.box', { from: { opacity: 0 }, to: { opacity: 1 }, duration: 0.5 })
+     *   .withRepeat(-1)
+     *   .onPageLoad()
+     *
+     * Motion('bounce', [entries])
+     *   .withRepeat({ times: 3, yoyo: true, delay: 0.2 })
+     *   .onPageLoad()
+     */
+    withRepeat(config: number | RepeatConfig): this;
     /**
      * Get or set progress (0-1)
      */
@@ -282,6 +339,10 @@ export declare class Timeline {
      * Check if timeline is currently active
      */
     isActive(): boolean;
+    /**
+     * Check if timeline is currently playing in reverse direction
+     */
+    reversed(): boolean;
     /**
      * Get timeline name
      */

package/dist/easing/index.d.ts CHANGED Viewed

@@ -2,7 +2,10 @@
  * Easing Functions
  *
  * All easings are based on Robert Penner's easing equations
- * and normalized to accept/return values in the 0-1 range
+ * and normalized to accept/return values in the 0-1 range.
+ *
+ * Includes GSAP-compatible aliases (quad, cubic, quart, quint, strong)
+ * and special easings (slow, rough) for migration compatibility.
  */
 import type { EasingFunction } from '../types';
 export declare const linear: (t: number) => number;
@@ -27,6 +30,31 @@ export declare const power4: {
     out: (t: number) => number;
     inOut: (t: number) => number;
 };
+export declare const quad: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const cubic: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const quart: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const quint: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
+export declare const strong: {
+    in: (t: number) => number;
+    out: (t: number) => number;
+    inOut: (t: number) => number;
+};
 export declare const sine: {
     in: (t: number) => number;
     out: (t: number) => number;
@@ -57,6 +85,21 @@ export declare const bounce: {
     out: (t: number) => number;
     inOut: (t: number) => number;
 };
+export declare const slow: {
+    in: EasingFunction;
+    out: EasingFunction;
+    inOut: EasingFunction;
+};
+export declare const rough: {
+    in: EasingFunction;
+    out: EasingFunction;
+    inOut: EasingFunction;
+};
+export declare const steps: {
+    in: EasingFunction;
+    out: EasingFunction;
+    inOut: EasingFunction;
+};
 /**
  * Get an easing function by string name
  * @param name Easing name (case insensitive)