@motion.page/sdk 1.0.8 → 1.1.1

package/README.md

@@ -18,6 +18,7 @@ A high-performance animation SDK with a declarative API. Scroll-triggered animat
 - [API Reference](#api-reference)
   - [Motion()](#motion-function)
   - [Motion Static Methods](#motion-static-methods)
+  - [Motion.context](#motioncontext--dynamic-content--spa)
   - [Motion.utils](#motionutils)
   - [Timeline](#timeline)
   - [Triggers](#triggers)
@@ -282,6 +283,7 @@ Calling `Motion()` with the same name on an already-existing timeline returns it
 | `Motion.reset` | `(targets: TargetInput): void` | Kill animations targeting those elements, revert text splits, clear transform cache and inline animation styles. |
 | `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). |
 
 #### Examples
 
@@ -302,6 +304,46 @@ Motion.cleanup();
 Motion.reset('.animated-card');
 ```
 
+#### Motion.context — Dynamic Content & SPA
+
+Use `Motion.context()` when DOM content changes without a full page reload (AJAX filters, SPA routing, infinite scroll, pagination). It tracks all timelines created inside the callback, enabling clean teardown and re-initialization.
+
+```ts
+// Create a context — all Motion() calls inside are tracked
+const ctx = Motion.context(() => {
+  Motion('hero', '.title', {
+    from: { opacity: 0, y: 30 },
+    duration: 0.8,
+  }).onPageLoad();
+
+  Motion('cards', '.card', {
+    from: { y: 100 },
+    duration: 1,
+  }).onScroll({ scrub: true });
+});
+
+// After AJAX content replacement:
+ctx.refresh();  // kills old animations, re-runs init, selectors re-resolve
+
+// React cleanup:
+useEffect(() => {
+  const ctx = Motion.context(() => { /* animations */ });
+  return () => ctx.revert();  // clean teardown on unmount
+}, []);
+
+// Astro view transitions:
+let ctx;
+document.addEventListener('astro:page-load', () => {
+  ctx?.revert();
+  ctx = Motion.context(() => { /* animations */ });
+});
+
+// Add more animations to existing context (e.g., lazy-loaded content):
+ctx.add(() => {
+  Motion('lazy', '.lazy-card', { from: { opacity: 0 }, duration: 0.5 }).onScroll({ scrub: true });
+});
+```
+
 ---
 
 ### Motion.utils
@@ -919,6 +961,7 @@ interface AnimationConfig {
   repeat?:   number | RepeatConfig; // Repeat count shorthand or full config (see below)
   split?:    SplitType;             // Text splitting for per-char/word/line animation
   mask?:     boolean;               // Wrap split elements in overflow:hidden for reveal effects
+  flap?:     FlapConfig;            // Split-flap / character scramble animation
   fit?:      FitConfig;             // FLIP-style morph toward another element
   axis?:     'x' | 'y';            // Axis binding for onMouseMove animations
 
@@ -969,6 +1012,9 @@ outlineColor, textDecorationColor, caretColor
 fill, stroke                               // string (CSS color)
 drawSVG                                    // string | { start?: number; end?: number }
 
+// Clipping
+'clip-path' / clipPath                     // string (CSS clip-path shape function)
+
 // Motion path
 path: {
   target:   string | Element;             // SVG <path> selector, element, or raw path data (starts with M/m)
@@ -1012,6 +1058,49 @@ Motion('draw-partial', '#circle', {
 }).play();
 ```
 
+### clip-path
+
+Animate the CSS `clip-path` property by interpolating between two shape functions of the **same type**. Both `clip-path` (kebab) and `clipPath` (camel) are accepted as the property name.
+
+| Shape | Format |
+|-------|--------|
+| `circle()` | `circle(<radius> at <x> <y>)` |
+| `ellipse()` | `ellipse(<rx> <ry> at <x> <y>)` |
+| `inset()` | `inset(<top> <right>? <bottom>? <left>? round <radius>?)` |
+| `polygon()` | `polygon(<x1> <y1>, <x2> <y2>, …)` |
+| `rect()` | `rect(<top> <right> <bottom> <left> round <radius>?)` |
+| `xywh()` | `xywh(<x> <y> <w> <h> round <radius>?)` |
+
+**Interpolation rules:**
+- Start and end must use the **same shape function** (e.g. `circle → circle`). Cross-shape animations snap to the end value at progress ≥ 0.5 (no smooth morphing across types).
+- Polygon animations require **the same vertex count** on both ends — otherwise the animation hard-swaps at the midpoint.
+- Each numeric component is linearly interpolated; CSS units (`%`, `px`, `em`, etc.) are preserved.
+- The renderer writes both `clip-path` and `-webkit-clip-path` so older Safari renders correctly.
+
+```ts
+// Reveal an image by expanding a circular mask
+Motion('reveal', '.cover', {
+  from: { 'clip-path': 'circle(0% at 50% 50%)' },
+  to:   { 'clip-path': 'circle(75% at 50% 50%)' },
+  duration: 0.8,
+  ease: 'power2.out',
+}).onScroll({ scrub: true });
+
+// Inset crop animation (camelCase form also works)
+Motion('crop', '.image', {
+  from: { clipPath: 'inset(0px round 0px)' },
+  to:   { clipPath: 'inset(20px round 16px)' },
+  duration: 0.6,
+}).onHover({ onLeave: 'reverse' });
+
+// Polygon slide-in (vertex counts must match)
+Motion('slide', '.panel', {
+  from: { 'clip-path': 'polygon(0% 0%, 0% 0%, 0% 100%, 0% 100%)' },
+  to:   { 'clip-path': 'polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)' },
+  duration: 0.5,
+}).onPageLoad();
+```
+
 ### path
 
 `path.target` accepts a CSS selector, an `Element`, or raw SVG path data (a string starting with `M` or `m`):
@@ -1163,6 +1252,126 @@ Motion('reveal', 'h1', {
 }).onPageLoad();
 ```
 
+### flap
+
+When `flap` is set (together with `split: 'chars'`), each character cycles through random intermediate characters before landing on its final value — creating split-flap display, scramble, or decode effects.
+
+```ts
+interface FlapConfig {
+  /** Visual transition style. Default: 'flip' */
+  type?: 'flip' | 'fade' | 'slide' | 'blur' | 'scale' | 'board' | 'none';
+  /** Character set to cycle through. Default: 'alphanumeric' */
+  charset?: CharsetPreset | string;
+  /** Number of random cycles before resolving. Range tuple [min, max] picks randomly per character. Default: [2, 5] */
+  cycles?: number | [number, number];
+  /** Perspective depth (px) for 3D flip/board transitions. Default: 400 */
+  perspective?: number;
+  /** Realistic departure-board styling for 'board' type (dark gradient, split line). Default: true */
+  styledBoard?: boolean;
+  /**
+   * Strategy for preventing layout shift during cycling:
+   *   - false (default)   → no pinning; text width flexes naturally
+   *   - true | 'cells'    → pin each cell to the widest glyph (classic split-flap look)
+   *   - 'container'       → pin the element's outer width only, letters flow naturally
+   *                         (best for inline hover flappers on nav links)
+   */
+  stableWidth?: boolean | 'cells' | 'container';
+  /** Board type: render blank cells for space characters instead of skipping them. Default: false */
+  preserveWhitespaceCells?: boolean;
+}
+```
+
+**Type styles:**
+- `'flip'` — 3D CSS rotateX card flip
+- `'fade'` — CSS opacity fade out/in
+- `'slide'` — CSS translateY slide out/in
+- `'blur'` — CSS filter blur out/in
+- `'scale'` — CSS scale pop/shrink
+- `'board'` — mechanical split-flap departure board with two-sided flap, shadow, and split line
+- `'none'` — No built-in visual effect. Use with `from`/`to` to create fully custom flap animations
+
+#### Charset presets
+
+| Preset | Characters |
+|--------|-----------|
+| `'alphanumeric'` | A–Z 0–9 |
+| `'alpha'` | A–Z |
+| `'numeric'` | 0–9 |
+| `'hex'` | 0–9 A–F |
+| `'binary'` | 0 1 |
+| `'katakana'` | ァ–ン (Japanese katakana) |
+| `'symbols'` | `!@#$%^&*` etc. |
+| `'blocks'` | ░ ▒ ▓ █ |
+
+Pass any custom string to cycle through your own characters: `charset: 'ABCXYZ'`.
+
+```ts
+// Styled departure board with split-flap effect
+Motion('board', '.departure-text', {
+  split: 'chars',
+  flap: { type: 'board', styledBoard: true },
+  stagger: 0.05,
+}).onPageLoad();
+
+// Classic flip animation
+Motion('flip', '.title', {
+  split: 'chars',
+  flap: { type: 'flip', cycles: 6 },
+  stagger: 0.05,
+}).onPageLoad();
+
+// Matrix-style katakana decode with random resolve order
+Motion('matrix', '.terminal', {
+  split: 'chars',
+  flap: { type: 'fade', charset: 'katakana', cycles: [4, 8] },
+  stagger: { each: 0.03, from: 'random' },
+}).onPageLoad();
+
+// Combine flap with CSS opacity + translate
+Motion('combo', 'h1', {
+  split: 'chars',
+  flap: { type: 'flip', cycles: 4 },
+  from: { opacity: 0, y: 20 },
+  to: { opacity: 1, y: 0 },
+  stagger: 0.04,
+  duration: 0.8,
+}).onPageLoad();
+```
+
+#### Per-cycle composition
+
+When `flap` is present, all `from`/`to` properties animate **per character-swap cycle** instead of once over the full animation duration. Each cycle follows a V-curve: starts at `to`, dips to `from` at the midpoint (when the character swaps), then returns to `to`.
+
+This lets you layer any CSS property on top of any flap type:
+
+```ts
+// Flip + fade + slide on every cycle
+Motion('heading', '.title', {
+  split: 'chars',
+  flap: { type: 'flip' },
+  from: { opacity: 0, y: 20 },
+  to: { opacity: 1, y: 0 },
+  duration: 2,
+  stagger: 0.05,
+}).play();
+```
+
+Use `type: 'none'` to build fully custom flap effects — no built-in visual, just character cycling driven entirely by your `from`/`to` properties:
+
+```ts
+// Custom scale-bounce flap with no built-in effect
+Motion('custom-flap', '.label', {
+  split: 'chars',
+  flap: { type: 'none', cycles: 3 },
+  from: { scale: 0, opacity: 0 },
+  to: { scale: 1, opacity: 1 },
+  duration: 1.5,
+  stagger: 0.05,
+}).play();
+```
+
+> **Note:** `fade` owns `opacity` and `blur` owns `filter` — these types strip conflicting user properties. Use `flip`, `scale`, `slide`, `board`, or `none` if you need full `from`/`to` control over those properties.
+
 ### FitConfig
 
 FLIP-style morph animation. When `fit` is set, `from` and `to` are ignored — the SDK measures both elements' bounding rects at play time and animates the visual delta between them.
@@ -1246,6 +1455,8 @@ import type {
   SplitType,
   PathConfig,
   FitConfig,
+  FlapConfig,
+  CharsetPreset,
 
   // Triggers
   HoverConfig,

package/dist/core/AnimationBuilder.d.ts

@@ -4,7 +4,7 @@
  * Creates animations from configuration objects.
  * Used internally by Motion() function.
  */
-import type { AnimationVars, AnimationTarget, TargetInput, StaggerVars, SplitType, AnimationConfig, FitConfig } from '../types';
+import type { AnimationVars, AnimationTarget, TargetInput, StaggerVars, SplitType, AnimationConfig, FitConfig, FlapConfig } from '../types';
 /**
  * Internal builder configuration for cloning (not exported from SDK)
  */
@@ -17,6 +17,7 @@ interface BuilderConfig {
     ease: string;
     axis?: 'x' | 'y';
     fit?: FitConfig;
+    flap?: FlapConfig;
     split?: SplitType;
     mask?: boolean;
     stagger?: number | StaggerVars;
@@ -56,6 +57,7 @@ export declare class AnimationBuilder {
     private _stagger?;
     private _axis?;
     private _fitConfig?;
+    private _flapConfig?;
     private _onStart?;
     private _onUpdate?;
     private _onComplete?;
@@ -105,6 +107,10 @@ export declare class AnimationBuilder {
      * Whether this builder uses text splitting
      */
     hasSplit(): boolean;
+    /**
+     * Whether this builder uses text flapper
+     */
+    hasFlap(): boolean;
     private _resetBuildState;
     /**
      * Get builder configuration for cloning (used by Timeline's each mode)

package/dist/core/Engine.d.ts

@@ -23,6 +23,7 @@ export declare class Engine {
     private totalCreated;
     private _animationSnapshot;
     private timelines;
+    private _captureTarget;
     private ticker;
     private animationPool;
     private propTweenPool;
@@ -79,9 +80,22 @@ export declare class Engine {
      */
     getTotalCreated(): number;
     /**
-     * Get or create a named timeline
+     * Get or create a named timeline.
+     * When a context capture is active, the timeline name is recorded into
+     * the capture set so that MotionContext can track ownership.
      */
     getTimeline(name: string): Timeline;
+    /**
+     * Start capturing timeline names into the provided set.
+     * Used by MotionContext to track which timelines belong to a context.
+     * @internal
+     */
+    startCapture(target: Set<string>): void;
+    /**
+     * Stop capturing timeline names.
+     * @internal
+     */
+    stopCapture(): void;
     /**
      * Check if timeline exists
      */

package/dist/core/Motion.d.ts

@@ -25,6 +25,7 @@
  */
 import type { TargetInput, AnimationConfig, AnimationEntry, AnimationVars } from '../types';
 import { Timeline } from './Timeline';
+import { MotionContext } from './MotionContext';
 /**
  * Motion function overloads
  */
@@ -41,6 +42,7 @@ declare namespace MotionFunction {
     var killAll: () => void;
     var refreshScrollTriggers: () => void;
     var cleanup: () => void;
+    var context: (fn: () => void) => MotionContext;
     var utils: {
         readonly toArray: typeof import("../utils/MotionUtils").toArray;
         readonly clamp: typeof import("../utils/MotionUtils").clamp;

package/dist/core/MotionContext.d.ts

@@ -0,0 +1,77 @@
+/**
+ * MotionContext — Scoped animation lifecycle management
+ *
+ * Tracks all timelines created during a callback execution, enabling
+ * clean teardown and re-initialization when DOM content changes.
+ *
+ * Solves the universal "dynamic content" problem:
+ * - WordPress AJAX filters (Bricks, WooCommerce, Jetpack)
+ * - SPA navigation (React, Astro view transitions, Next.js)
+ * - Infinite scroll / pagination
+ * - Any scenario where DOM elements are replaced without a full page reload
+ *
+ * @example WordPress (generated code)
+ * const ctx = Motion.context(() => {
+ *   Motion('hero', '.title', { from: { opacity: 0 }, to: { opacity: 1 } }).onPageLoad()
+ *   Motion('cards', '.card', { from: { y: 100 }, to: { y: 0 } }).onScroll({ scrub: true })
+ * })
+ * // After AJAX filter replaces content:
+ * ctx.refresh()
+ *
+ * @example React
+ * useEffect(() => {
+ *   const ctx = Motion.context(() => {
+ *     Motion('fade', '.box', { from: { opacity: 0 }, to: { opacity: 1 } }).onScroll({ scrub: true })
+ *   })
+ *   return () => ctx.revert()
+ * }, [])
+ *
+ * @example Astro (view transitions)
+ * document.addEventListener('astro:page-load', () => {
+ *   window._ctx?.revert()
+ *   window._ctx = Motion.context(() => { ... })
+ * })
+ */
+export declare class MotionContext {
+    /** The init function that creates animations — re-executed on refresh() */
+    private _fn;
+    /** Timeline names created within this context */
+    private _timelineNames;
+    /** Whether this context has been reverted (prevents double-revert) */
+    private _reverted;
+    constructor(fn: () => void);
+    /**
+     * Kill all timelines created in this context, restore elements to their
+     * initial CSS state, and clean up DOM artifacts (ScrollTrigger spacers/markers).
+     *
+     * After revert(), the context is empty and can be refreshed or discarded.
+     */
+    revert(): void;
+    /**
+     * Revert all animations and re-execute the init function.
+     * Selectors are re-resolved against the current DOM, so new/replaced
+     * elements are picked up automatically.
+     *
+     * This is the primary method for handling dynamic content changes.
+     */
+    refresh(): void;
+    /**
+     * Add more animations to this context without affecting existing ones.
+     * Useful for lazy-loaded content or progressive enhancement.
+     *
+     * @example
+     * ctx.add(() => {
+     *   Motion('lazy-section', '.lazy-card', { ... }).onScroll({ scrub: true })
+     * })
+     */
+    add(fn: () => void): void;
+    /**
+     * Get the timeline names tracked by this context (for debugging/testing).
+     */
+    getTimelineNames(): string[];
+    /**
+     * Execute a function while capturing timeline names into this context.
+     * Uses Engine's capture mechanism for zero-overhead tracking.
+     */
+    private _execute;
+}

package/dist/core/PropTween.d.ts

@@ -8,8 +8,9 @@
 import type { AnimationTarget } from '../types';
 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';
+type PropTweenValueType = 'scalar' | 'color' | 'filter' | 'drawSVG' | 'path' | 'clipPath';
 export declare class PropTween {
     target: AnimationTarget | null;
     property: string;
@@ -27,6 +28,8 @@ export declare class PropTween {
     startDraw: ParsedDrawSVG | null;
     endDraw: ParsedDrawSVG | null;
     pathLength: number;
+    startClipPath: ParsedClipPath | null;
+    endClipPath: ParsedClipPath | null;
     pathData: string | null;
     motionPathLength: number;
     startProgress: number;
@@ -54,6 +57,10 @@ export declare class PropTween {
      * Initialize the PropTween with filter values
      */
     initFilter(target: AnimationTarget, property: string, startFilters: ParsedFilterFunction[], endFilters: ParsedFilterFunction[]): this;
+    /**
+     * Initialize the PropTween with clip-path values
+     */
+    initClipPath(target: AnimationTarget, property: string, startClipPath: ParsedClipPath, endClipPath: ParsedClipPath): this;
     /**
      * Initialize the PropTween with drawSVG values
      */

package/dist/core/Timeline.d.ts

@@ -326,10 +326,14 @@ export declare class Timeline {
     /**
      * Kill timeline and all children, reset all state
      * @param clearProps - If true (default), restore elements to their initial CSS values
+     *
+     * Any text splits owned by this timeline's builders are reverted via
+     * SDKRegistry.textSplitter.revert() (reference-counted — safe when
+     * other timelines still share the split element).
      */
     kill(clearProps?: boolean): void;
     /**
-     * Check if timeline is currently active
+     * Check if timeline is currently active.
      */
     isActive(): boolean;
     /**