@motion.page/sdk 1.2.2 → 1.2.4

package/README.md

@@ -19,6 +19,7 @@ A high-performance animation SDK with a declarative API. Scroll-triggered animat
   - [Motion()](#motion-function)
   - [Motion Static Methods](#motion-static-methods)
   - [Motion.context](#motioncontext--dynamic-content--spa)
+  - [Motion.responsive](#motionresponsive--responsive-breakpoint-variants)
   - [Motion.utils](#motionutils)
   - [Timeline](#timeline)
   - [Triggers](#triggers)
@@ -284,6 +285,7 @@ Calling `Motion()` with the same name on an already-existing timeline returns it
 | `Motion.refreshScrollTriggers` | `(): void` | Recalculate all scroll trigger start/end positions (call after layout changes). |
 | `Motion.cleanup` | `(): void` | Remove ScrollTrigger spacer and marker DOM nodes from the document. |
 | `Motion.context` | `(fn: () => void): MotionContext` | Create a scoped context that tracks all timelines created during `fn()`. Returns a `MotionContext` with `revert()`, `refresh()`, and `add(fn)` methods. Essential for dynamic content (AJAX filters, SPA navigation, infinite scroll). |
+| `Motion.responsive` | `(name, variants, breakpoints): ResponsiveManager` | Register a reactive timeline whose per-breakpoint variant is live-swapped as the viewport crosses a breakpoint — no page reload. `variants` is a sparse map of `desktop` / `laptop` / `tablet` / `phone` factories; `breakpoints` is `{ laptops, tablets, phones }` in px. Returns a manager with `getActiveTier()` and `destroy()`. |
 
 #### Examples
 
@@ -344,6 +346,53 @@ ctx.add(() => {
 });
 ```
 
+#### Motion.responsive — Responsive Breakpoint Variants
+
+Use `Motion.responsive()` to give one timeline a different animation per viewport tier. Instead of compiling a separate block per breakpoint, you register a **sparse map of variant factories** and the SDK live-swaps the active variant as the viewport crosses a breakpoint — it kills the previous tier's timeline and builds the new one, with **no page reload**.
+
+```ts
+Motion.responsive(
+  'hero',
+  {
+    // Each tier is a factory that builds AND registers its timeline.
+    desktop: () =>
+      Motion('hero', '.title', {
+        from: { opacity: 0, x: -120 },
+        duration: 1,
+      }).onPageLoad(),
+
+    phone: () =>
+      Motion('hero', '.title', {
+        from: { opacity: 0, y: 40 },
+        duration: 0.6,
+      }).onPageLoad(),
+  },
+  { laptops: 992, tablets: 768, phones: 576 } // breakpoint boundaries in px
+);
+```
+
+**Tiers & ranges.** There are four tiers — `desktop`, `laptop`, `tablet`, `phone`. The `breakpoints` object sets the boundaries, and each tier owns a width range (with the values above):
+
+| Tier | Active range |
+|------|--------------|
+| `desktop` | `≥ 993px` (above `laptops`) |
+| `laptop` | `769px – 992px` |
+| `tablet` | `577px – 768px` |
+| `phone` | `≤ 576px` (at or below `phones`) |
+
+**Sparse maps cascade up.** You only define the tiers you care about. A tier with no variant falls back to the nearest **wider** tier that does. In the example above, `laptop` and `tablet` widths both use the `desktop` variant; only `phone` width switches to the phone variant.
+
+**Return value — the manager.** `Motion.responsive()` returns a `ResponsiveManager`:
+
+```ts
+const hero = Motion.responsive('hero', { /* variants */ }, { laptops: 992, tablets: 768, phones: 576 });
+
+hero.getActiveTier(); // 'desktop' | 'laptop' | 'tablet' | 'phone' | null — the tier currently driving the page
+hero.destroy();       // remove the breakpoint listeners and kill the active variant
+```
+
+> In SSR or environments without `matchMedia`, the `desktop` variant is built once with no live swapping. If the responsive runtime is tree-shaken out of a custom bundle that has no responsive timelines, the call best-effort builds the `desktop` variant and returns `undefined`.
+
 ---
 
 ### Motion.utils

package/dist/core/Animation.d.ts

@@ -226,6 +226,13 @@ export declare class Animation {
      * @internal - Use only within sdk package for property inspection (e.g. captureStartValues).
      */
     getFirstPropTween(): PropTween | null;
+    /**
+     * Mark motion-path geometry stale on every prop tween so the geometry-dependent
+     * offsets re-resolve on the next render. Called after a layout-shifting event
+     * (window.load / resize ScrollTrigger refresh) so paths aligned to an
+     * asynchronously-sized target settle onto the correct position.
+     */
+    invalidatePathGeometry(): void;
     /**
      * Add a property tween to the linked list
      */

package/dist/core/PropTween.d.ts

@@ -10,7 +10,7 @@ import type { ParsedFilterFunction } from '../utils/FilterParser';
 import type { ParsedDrawSVG } from '../utils/DrawSVGParser';
 import type { ParsedClipPath } from '../utils/ClipPathParser';
 import { type PathPoint } from '../utils/PathParser';
-type PropTweenValueType = 'scalar' | 'color' | 'filter' | 'drawSVG' | 'path' | 'clipPath';
+type PropTweenValueType = 'scalar' | 'string' | 'color' | 'filter' | 'drawSVG' | 'path' | 'clipPath';
 export declare class PropTween {
     target: AnimationTarget | null;
     property: string;
@@ -22,6 +22,8 @@ export declare class PropTween {
     endUnit: string | null;
     next: PropTween | null;
     valueType: PropTweenValueType;
+    startString: string;
+    endString: string;
     startColor: Float32Array | null;
     endColor: Float32Array | null;
     changeColor: Float32Array;
@@ -46,11 +48,22 @@ export declare class PropTween {
         y: number;
     } | null;
     pathLUT: PathPoint[] | null;
+    pathAlignTarget: string | Element | null;
+    pathAlignAt: [number, number] | null;
+    pathTarget: string | Element | null;
+    pathScaleX: number;
+    pathScaleY: number;
     private _isElement;
+    private _pathGeomResolved;
     /**
      * Initialize the PropTween with scalar values
      */
     init(target: AnimationTarget, property: string, startValue: number, endValue: number, unit?: string, startUnit?: string, endUnit?: string): this;
+    /**
+     * Initialize the PropTween with a compound CSS string value
+     * (transform-origin, background-position, …).
+     */
+    initString(target: AnimationTarget, property: string, startString: string, endString: string): this;
     /**
      * Initialize the PropTween with color values
      */
@@ -77,7 +90,36 @@ export declare class PropTween {
     }, pathOffset: {
         x: number;
         y: number;
-    }): this;
+    }, pathScale?: {
+        x: number;
+        y: number;
+    }, alignTarget?: string | Element, alignAt?: [number, number], pathTarget?: string | Element): this;
+    /**
+     * Sample the path into the lookup table at the given user-unit -> screen-px scale.
+     * Releases any previously-held LUT back to the pool before re-sampling.
+     */
+    private _buildPathLUT;
+    /**
+     * Resolve the geometry-dependent path offsets (alignOffset/pathOffset/pathScale)
+     * against the live, laid-out element.
+     *
+     * The offsets are first computed at parse time, but a target sized asynchronously
+     * (Lottie injecting its <svg>, lazy-loaded <img>, web-font reflow) can report a
+     * 0×0 / 0-height box then. That bakes `alignOffset = {x: w/2, y: 0}` — anchoring
+     * the element by its TOP edge instead of its CENTER — which is invisible on the
+     * straight runs of a path but drifts the element off curves (where it rotates).
+     *
+     * We therefore defer: each frame until the element has a real (non-degenerate)
+     * box, recompute from the live geometry, then lock in. Once resolved there is no
+     * per-frame cost. Only aligned DOM-element motion paths participate; raw path-data
+     * or plain-object targets keep their parse-time values unchanged.
+     */
+    private _resolvePathGeometryIfNeeded;
+    /**
+     * Mark the path geometry stale so it re-resolves on the next render. Called when
+     * layout may have shifted (window.load / resize ScrollTrigger refresh).
+     */
+    invalidatePathGeometry(): void;
     /**
      * Render the property at given progress (0-1)
      */

package/dist/core/Timeline.d.ts

@@ -385,6 +385,12 @@ export declare class Timeline {
      * @internal
      */
     getFirstChildAnimation(): Animation | null;
+    /**
+     * Propagate a motion-path geometry invalidation to every descendant animation,
+     * so aligned path offsets re-resolve against post-layout geometry on the next
+     * render. Called from ScrollTrigger.refresh() (window.load / resize).
+     */
+    invalidatePathGeometry(): void;
     /**
      * Get first child builder (for split-aware trigger target resolution).
      * When text splitting is active, the builder holds original pre-split targets.