@hyperframes/core 0.6.91 → 0.6.93

package/dist/parsers/gsapParser.js

@@ -11,6 +11,8 @@
 import * as recast from "recast";
 import { parse as babelParse } from "@babel/parser";
 export { serializeGsapAnimations, getAnimationsForElementId, validateCompositionGsap, keyframesToGsapAnimations, gsapAnimationsToKeyframes, SUPPORTED_PROPS, SUPPORTED_EASES, } from "./gsapSerialize";
+export { PROPERTY_GROUPS, classifyPropertyGroup, classifyTweenPropertyGroup, } from "./gsapConstants";
+import { classifyPropertyGroup, classifyTweenPropertyGroup } from "./gsapConstants";
 export { generateSpringEaseData, SPRING_PRESETS } from "./springEase";
 const GSAP_METHODS = new Set(["set", "to", "from", "fromTo"]);
 function parseScript(script) {
@@ -279,15 +281,34 @@ function isGsapTimelineCall(node) {
         node.callee.object?.name === "gsap" &&
         node.callee.property?.name === "timeline");
 }
-function findTimelineVar(ast) {
+function extractTimelineDefaults(callNode, scope) {
+    const arg = callNode.arguments?.[0];
+    if (!arg || arg.type !== "ObjectExpression")
+        return undefined;
+    const defaultsProp = arg.properties?.find((p) => isObjectProperty(p) && propKeyName(p) === "defaults");
+    if (!defaultsProp?.value || defaultsProp.value.type !== "ObjectExpression")
+        return undefined;
+    const record = objectExpressionToRecord(defaultsProp.value, scope);
+    const result = {};
+    if (typeof record.ease === "string")
+        result.ease = record.ease;
+    if (typeof record.duration === "number")
+        result.duration = record.duration;
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+function findTimelineVar(ast, scope) {
     let timelineVar = null;
     let timelineCount = 0;
+    let defaults;
+    const emptyScope = scope ?? new Map();
     recast.types.visit(ast, {
         visitVariableDeclarator(path) {
             if (isGsapTimelineCall(path.node.init)) {
                 timelineCount += 1;
-                if (!timelineVar)
+                if (!timelineVar) {
                     timelineVar = path.node.id?.name ?? null;
+                    defaults = extractTimelineDefaults(path.node.init, emptyScope);
+                }
             }
             this.traverse(path);
         },
@@ -298,12 +319,13 @@ function findTimelineVar(ast) {
                     const left = path.node.left;
                     if (left?.type === "Identifier")
                         timelineVar = left.name;
+                    defaults = extractTimelineDefaults(path.node.right, emptyScope);
                 }
             }
             this.traverse(path);
         },
     });
-    return { timelineVar, timelineCount };
+    return { timelineVar, timelineCount, defaults };
 }
 /**
  * True when the member chain of `callNode.callee` is rooted at the timeline
@@ -531,13 +553,13 @@ function parseObjectArrayKeyframes(node, scope) {
     if (totalDuration > 0) {
         let cumulative = 0;
         for (const entry of raw) {
+            cumulative += entry.duration ?? 0;
             const percentage = Math.round((cumulative / totalDuration) * 100);
             keyframes.push({
                 percentage,
                 properties: entry.properties,
                 ...(entry.ease ? { ease: entry.ease } : {}),
             });
-            cumulative += entry.duration ?? 0;
         }
     }
     else {
@@ -759,7 +781,8 @@ function tweenCallToAnimation(call, scope) {
             }
         }
     }
-    const posVal = call.positionArg ? extractLiteralValue(call.positionArg, scope) : 0;
+    const hasPositionArg = !!call.positionArg;
+    const posVal = hasPositionArg ? extractLiteralValue(call.positionArg, scope) : 0;
     const position = typeof posVal === "number" ? posVal : typeof posVal === "string" ? posVal : 0;
     let duration = typeof vars.duration === "number" ? vars.duration : undefined;
     const ease = typeof vars.ease === "string" ? vars.ease : undefined;
@@ -775,6 +798,19 @@ function tweenCallToAnimation(call, scope) {
         duration,
         ease,
     };
+    if (!hasPositionArg)
+        anim.implicitPosition = true;
+    let group = classifyTweenPropertyGroup(properties);
+    if (!group && keyframesData) {
+        const kfProps = {};
+        for (const kf of keyframesData.keyframes) {
+            for (const k of Object.keys(kf.properties))
+                kfProps[k] = true;
+        }
+        group = classifyTweenPropertyGroup(kfProps);
+    }
+    if (group)
+        anim.propertyGroup = group;
     if (Object.keys(extras).length > 0)
         anim.extras = extras;
     if (keyframesData)
@@ -787,14 +823,101 @@ function tweenCallToAnimation(call, scope) {
         anim.hasUnresolvedSelector = true;
     return anim;
 }
+// ── Timeline Position Resolution ──────────────────────────────────────────
+const GSAP_DEFAULT_DURATION = 0.5;
+// NOTE: Label-based positions (e.g. "myLabel+=0.5") are not yet resolved —
+// they fall through to parseFloat which returns null for non-numeric strings.
+function resolvePositionString(pos, cursor, prevStart) {
+    const trimmed = pos.trim();
+    if (trimmed === "")
+        return cursor;
+    if (trimmed.startsWith("+=")) {
+        const n = Number.parseFloat(trimmed.slice(2));
+        return Number.isFinite(n) ? cursor + n : null;
+    }
+    if (trimmed.startsWith("-=")) {
+        const n = Number.parseFloat(trimmed.slice(2));
+        return Number.isFinite(n) ? cursor - n : null;
+    }
+    if (trimmed === "<")
+        return prevStart;
+    if (trimmed === ">")
+        return cursor;
+    if (trimmed.startsWith("<")) {
+        const n = Number.parseFloat(trimmed.slice(1));
+        return Number.isFinite(n) ? prevStart + n : null;
+    }
+    if (trimmed.startsWith(">")) {
+        const n = Number.parseFloat(trimmed.slice(1));
+        return Number.isFinite(n) ? cursor + n : null;
+    }
+    const n = Number.parseFloat(trimmed);
+    return Number.isFinite(n) ? n : null;
+}
+function applyTimelineDefaults(anims, defaults) {
+    if (!defaults)
+        return;
+    for (const anim of anims) {
+        if (anim.method === "set")
+            continue;
+        if (anim.duration === undefined && defaults.duration !== undefined) {
+            anim.duration = defaults.duration;
+        }
+        if (anim.ease === undefined && defaults.ease !== undefined) {
+            anim.ease = defaults.ease;
+        }
+    }
+}
+function resolveTimelinePositions(anims) {
+    let cursor = 0;
+    let prevStart = 0;
+    for (const anim of anims) {
+        const duration = anim.method === "set" ? 0 : (anim.duration ?? GSAP_DEFAULT_DURATION);
+        let start;
+        if (anim.implicitPosition) {
+            start = cursor;
+        }
+        else if (typeof anim.position === "number") {
+            start = anim.position;
+        }
+        else if (typeof anim.position === "string") {
+            start = resolvePositionString(anim.position, cursor, prevStart);
+        }
+        else {
+            start = cursor;
+        }
+        if (start != null) {
+            anim.resolvedStart = Math.max(0, start);
+            prevStart = anim.resolvedStart;
+            cursor = Math.max(cursor, anim.resolvedStart + duration);
+        }
+    }
+}
+function sortBySourcePosition(calls) {
+    calls.sort((a, b) => {
+        const aLoc = a.node.callee?.property?.loc?.start;
+        const bLoc = b.node.callee?.property?.loc?.start;
+        if (!aLoc || !bLoc)
+            return 0;
+        return aLoc.line - bLoc.line || aLoc.column - bLoc.column;
+    });
+}
 // ── Stable ID Generation ───────────────────────────────────────────────────
+/**
+ * IDs are transient — recomputed on every parse, never persisted across sessions.
+ * They exist only in ephemeral request/response payloads, React component state,
+ * and the in-memory keyframe cache (rebuilt on every page load). No database,
+ * localStorage, or file stores animation IDs, so changing the ID format (e.g.
+ * adding a `-scale`/`-position` suffix) is safe.
+ */
 function assignStableIds(anims) {
     const counts = new Map();
     return anims.map((anim) => {
         const posKey = typeof anim.position === "number"
             ? String(Math.round(anim.position * 1000))
             : String(anim.position);
-        const base = `${anim.targetSelector}-${anim.method}-${posKey}`;
+        const groupSuffix = anim.propertyGroup ? `-${anim.propertyGroup}` : "";
+        const base = `${anim.targetSelector}-${anim.method}-${posKey}${groupSuffix}`;
         const count = (counts.get(base) ?? 0) + 1;
         counts.set(base, count);
         const id = count === 1 ? base : `${base}-${count}`;
@@ -811,10 +934,14 @@ function parseGsapAst(script) {
     const ast = parseScript(script);
     const scope = collectScopeBindings(ast);
     const targetBindings = collectTargetBindings(ast, scope);
-    const detection = findTimelineVar(ast);
+    const detection = findTimelineVar(ast, scope);
     const timelineVar = detection.timelineVar ?? "tl";
     const calls = findAllTweenCalls(ast, timelineVar, scope, targetBindings);
-    const animations = assignStableIds(calls.map((call) => tweenCallToAnimation(call, scope)));
+    sortBySourcePosition(calls);
+    const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope));
+    applyTimelineDefaults(rawAnims, detection.defaults);
+    resolveTimelinePositions(rawAnims);
+    const animations = assignStableIds(rawAnims);
     const located = animations.map((animation, i) => ({
         id: animation.id,
         call: calls[i],
@@ -1137,7 +1264,11 @@ export function removeAnimationFromScript(script, animationId) {
         console.warn("[gsap-parser] removeAnimationFromScript parse failed:", e);
         return script;
     }
-    const target = parsed.located.find((l) => l.id === animationId);
+    let target = parsed.located.find((l) => l.id === animationId);
+    if (!target) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        target = parsed.located.find((l) => l.id === convertedId);
+    }
     if (!target)
         return script;
     const node = target.call.node;
@@ -1314,6 +1445,23 @@ function percentageFromKey(key) {
     const m = PERCENTAGE_KEY_RE.exec(key);
     return m ? Number.parseFloat(m[1]) : Number.NaN;
 }
+const PCT_TOLERANCE = 2;
+function findKeyframePropByPct(kfNode, percentage) {
+    const props = kfNode.properties;
+    for (let i = 0; i < props.length; i++) {
+        if (!isObjectProperty(props[i]))
+            continue;
+        const key = propKeyName(props[i]);
+        if (typeof key !== "string")
+            continue;
+        const parsed = percentageFromKey(key);
+        if (Number.isNaN(parsed))
+            continue;
+        if (Math.abs(parsed - percentage) <= PCT_TOLERANCE)
+            return { idx: i, prop: props[i] };
+    }
+    return null;
+}
 /** Build a keyframe value AST node from properties and optional ease. */
 function buildKeyframeValueNode(properties, ease) {
     const entries = Object.entries(properties).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
@@ -1368,7 +1516,11 @@ function collapseKeyframesToFlat(varsArg, record) {
  * updateKeyframeInScript.
  */
 function locateKeyframeCtx(script, animationId, percentage) {
-    const loc = locateAnimation(script, animationId);
+    let loc = locateAnimation(script, animationId);
+    if (!loc) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        loc = locateAnimation(script, convertedId);
+    }
     if (!loc)
         return null;
     const kfNode = findKeyframesObjectNode(loc.target.call.varsArg);
@@ -1404,10 +1556,19 @@ export function addKeyframeToScript(script, animationId, percentage, properties,
     }
     const pctKey = `${percentage}%`;
     const newValueNode = buildKeyframeValueNode(properties, ease);
-    // Replace if this percentage already exists
-    const existingIdx = kfNode.properties.findIndex((p) => isObjectProperty(p) && propKeyName(p) === pctKey);
-    if (existingIdx !== -1) {
-        kfNode.properties[existingIdx].value = newValueNode;
+    // Merge into existing keyframe at this percentage, or insert new
+    const existing = findKeyframePropByPct(kfNode, percentage);
+    if (existing) {
+        if (existing.prop.value?.type === "ObjectExpression") {
+            const existingRecord = objectExpressionToRecord(existing.prop.value, loc.parsed.scope);
+            const merged = { ...existingRecord };
+            for (const [k, v] of Object.entries(properties))
+                merged[k] = v;
+            existing.prop.value = buildKeyframeValueNode(merged, ease ?? (typeof existingRecord.ease === "string" ? existingRecord.ease : undefined));
+        }
+        else {
+            existing.prop.value = newValueNode;
+        }
     }
     else {
         // Build the new property node with a quoted percentage key
@@ -1488,10 +1649,11 @@ export function removeKeyframeFromScript(script, animationId, percentage) {
     const ctx = locateKeyframeCtx(script, animationId, percentage);
     if (!ctx)
         return script;
-    const { loc, kfNode, pctKey } = ctx;
-    const removeIdx = kfNode.properties.findIndex((p) => isObjectProperty(p) && propKeyName(p) === pctKey);
-    if (removeIdx === -1)
+    const { loc, kfNode } = ctx;
+    const match = findKeyframePropByPct(kfNode, percentage);
+    if (!match)
         return script;
+    const removeIdx = match.idx;
     kfNode.properties.splice(removeIdx, 1);
     const remainingKfs = filterPercentageProps(kfNode);
     if (remainingKfs.length < 2) {
@@ -1509,11 +1671,11 @@ export function updateKeyframeInScript(script, animationId, percentage, properti
     const ctx = locateKeyframeCtx(script, animationId, percentage);
     if (!ctx)
         return script;
-    const { loc, kfNode, pctKey } = ctx;
-    const existing = kfNode.properties.find((p) => isObjectProperty(p) && propKeyName(p) === pctKey);
-    if (!existing)
+    const { loc, kfNode } = ctx;
+    const match = findKeyframePropByPct(kfNode, percentage);
+    if (!match)
         return script;
-    existing.value = buildKeyframeValueNode(properties, ease);
+    match.prop.value = buildKeyframeValueNode(properties, ease);
     return recast.print(loc.parsed.ast).code;
 }
 /** Resolve from/to property maps for a tween being converted to keyframes. */
@@ -1527,31 +1689,46 @@ const CSS_IDENTITY = {
 function cssIdentityValue(prop) {
     return CSS_IDENTITY[prop] ?? 0;
 }
+/**
+ * Resolve the 0% (from) and 100% (to) property maps for a tween being
+ * converted to percentage keyframes.
+ *
+ * @param resolvedFromValues — Despite the "from" in the name (historical), these
+ *   are runtime-captured DOM values that override the conversion endpoint:
+ *   - For to():    overrides fromProps (the 0% state / where the element is now).
+ *   - For from():  overrides toProps  (the 100% state / where the element rests).
+ *   - For fromTo(): merges into toProps (the 100% endpoint the user is editing).
+ */
 function resolveConversionProps(anim, resolvedFromValues) {
     if (anim.method === "to") {
-        if (resolvedFromValues) {
-            return { fromProps: resolvedFromValues, toProps: { ...anim.properties } };
-        }
         const identityFrom = {};
         for (const [key, val] of Object.entries(anim.properties)) {
             if (val != null)
                 identityFrom[key] = typeof val === "number" ? cssIdentityValue(key) : val;
         }
-        return { fromProps: identityFrom, toProps: { ...anim.properties } };
+        const fromProps = resolvedFromValues
+            ? { ...identityFrom, ...resolvedFromValues }
+            : identityFrom;
+        return { fromProps, toProps: { ...anim.properties } };
     }
     if (anim.method === "from") {
-        if (resolvedFromValues) {
-            return { fromProps: { ...anim.properties }, toProps: resolvedFromValues };
-        }
         const identityTo = {};
         for (const [key, val] of Object.entries(anim.properties)) {
             if (val != null)
                 identityTo[key] = typeof val === "number" ? cssIdentityValue(key) : val;
         }
-        return { fromProps: { ...anim.properties }, toProps: identityTo };
-    }
-    // fromTo
-    return { fromProps: { ...(anim.fromProperties ?? {}) }, toProps: { ...anim.properties } };
+        const toProps = resolvedFromValues ? { ...identityTo, ...resolvedFromValues } : identityTo;
+        return { fromProps: { ...anim.properties }, toProps };
+    }
+    // fromTo(fromVars, toVars): anim.fromProperties = fromVars (0% state),
+    // anim.properties = toVars (100% state). resolvedFromValues contains the
+    // current DOM position from a drag — it represents the NEW destination, so
+    // it merges into toProps (the 100% endpoint the user is editing), NOT into
+    // fromProps. This is intentional and not inverted.
+    const toProps = resolvedFromValues
+        ? { ...anim.properties, ...resolvedFromValues }
+        : { ...anim.properties };
+    return { fromProps: { ...(anim.fromProperties ?? {}) }, toProps };
 }
 /** Strip editable properties and ease/keyframes keys from a varsArg. */
 function stripEditableAndEase(varsArg) {
@@ -1584,7 +1761,11 @@ function insertKeyframesProp(varsArg, fromProps, toProps, easeEach) {
  * the "to" state for `from()` tweens (the values the DOM would resolve to).
  */
 export function convertToKeyframesInScript(script, animationId, resolvedFromValues) {
-    const loc = locateAnimation(script, animationId);
+    let loc = locateAnimation(script, animationId);
+    if (!loc) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        loc = locateAnimation(script, convertedId);
+    }
     if (!loc)
         return script;
     const anim = loc.target.animation;
@@ -1611,7 +1792,11 @@ export function convertToKeyframesInScript(script, animationId, resolvedFromValu
  * last keyframe's properties.
  */
 export function removeAllKeyframesFromScript(script, animationId) {
-    const loc = locateAnimation(script, animationId);
+    let loc = locateAnimation(script, animationId);
+    if (!loc) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        loc = locateAnimation(script, convertedId);
+    }
     if (!loc)
         return script;
     const kfNode = findKeyframesObjectNode(loc.target.call.varsArg);
@@ -1636,7 +1821,11 @@ export function removeAllKeyframesFromScript(script, animationId) {
  * Called when the user first edits a dynamically-generated keyframe in the studio.
  */
 export function materializeKeyframesInScript(script, animationId, keyframes, easeEach, resolvedSelector) {
-    const loc = locateAnimation(script, animationId);
+    let loc = locateAnimation(script, animationId);
+    if (!loc) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        loc = locateAnimation(script, convertedId);
+    }
     if (!loc)
         return script;
     const varsArg = loc.target.call.varsArg;
@@ -1844,6 +2033,136 @@ export function removeArcPathFromScript(script, animationId) {
         segments: [],
     });
 }
+// ── Split Into Property Groups ────────────────────────────────────────────
+/**
+ * Split a multi-group tween into separate per-group tweens. Each resulting
+ * tween contains only properties belonging to one property group (position,
+ * scale, rotation, visual, etc.). `transformOrigin` stays with the group that
+ * has the most properties. If the tween already belongs to a single group,
+ * returns the script unchanged with the original ID.
+ */
+// fallow-ignore-next-line complexity
+export function splitIntoPropertyGroups(script, animationId) {
+    let loc = locateAnimation(script, animationId);
+    if (!loc) {
+        const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
+        loc = locateAnimation(script, convertedId);
+    }
+    if (!loc)
+        return { script, ids: [animationId] };
+    const anim = loc.target.animation;
+    // Collect the properties to partition. For keyframed tweens, gather the
+    // union of all properties across all keyframes. For flat tweens, use the
+    // tween's own properties map.
+    const allPropKeys = new Set();
+    if (anim.keyframes) {
+        for (const kf of anim.keyframes.keyframes) {
+            for (const k of Object.keys(kf.properties))
+                allPropKeys.add(k);
+        }
+    }
+    else {
+        for (const k of Object.keys(anim.properties))
+            allPropKeys.add(k);
+    }
+    // Partition properties into groups (excluding transformOrigin — handled below).
+    const groupProps = new Map();
+    for (const key of allPropKeys) {
+        if (key === "transformOrigin")
+            continue;
+        const group = classifyPropertyGroup(key);
+        let arr = groupProps.get(group);
+        if (!arr) {
+            arr = [];
+            groupProps.set(group, arr);
+        }
+        arr.push(key);
+    }
+    // Only one group (or zero) — no split needed.
+    if (groupProps.size <= 1)
+        return { script, ids: [anim.id] };
+    // Assign transformOrigin to the group with the most properties.
+    if (allPropKeys.has("transformOrigin")) {
+        let largestGroup;
+        let largestCount = 0;
+        for (const [group, props] of groupProps) {
+            if (props.length > largestCount) {
+                largestCount = props.length;
+                largestGroup = group;
+            }
+        }
+        if (largestGroup) {
+            groupProps.get(largestGroup).push("transformOrigin");
+        }
+    }
+    // Build per-group tweens and insert them, then remove the original.
+    let result = script;
+    // Remove the original tween first.
+    result = removeAnimationFromScript(result, anim.id);
+    // Insert one tween per group. Iteration order of the Map follows insertion
+    // order, which mirrors the order properties were encountered.
+    for (const [, props] of groupProps) {
+        const propSet = new Set(props);
+        if (anim.keyframes) {
+            // Build keyframes containing only this group's properties per keyframe.
+            const groupKeyframes = [];
+            for (const kf of anim.keyframes.keyframes) {
+                const filtered = {};
+                for (const [k, v] of Object.entries(kf.properties)) {
+                    if (propSet.has(k))
+                        filtered[k] = v;
+                }
+                // Skip keyframes where this group has zero properties.
+                if (Object.keys(filtered).length === 0)
+                    continue;
+                groupKeyframes.push({
+                    percentage: kf.percentage,
+                    properties: filtered,
+                    ...(kf.ease ? { ease: kf.ease } : {}),
+                });
+            }
+            if (groupKeyframes.length === 0)
+                continue;
+            const addResult = addAnimationWithKeyframesToScript(result, anim.targetSelector, typeof anim.position === "number" ? anim.position : 0, anim.duration ?? 0.5, groupKeyframes, anim.keyframes.easeEach ?? anim.ease);
+            result = addResult.script;
+        }
+        else {
+            // Flat tween — filter properties to this group.
+            const groupProperties = {};
+            for (const [k, v] of Object.entries(anim.properties)) {
+                if (propSet.has(k))
+                    groupProperties[k] = v;
+            }
+            if (Object.keys(groupProperties).length === 0)
+                continue;
+            let fromProperties;
+            if (anim.method === "fromTo" && anim.fromProperties) {
+                fromProperties = {};
+                for (const [k, v] of Object.entries(anim.fromProperties)) {
+                    if (propSet.has(k))
+                        fromProperties[k] = v;
+                }
+            }
+            const addResult = addAnimationToScript(result, {
+                targetSelector: anim.targetSelector,
+                method: anim.method,
+                position: anim.position,
+                duration: anim.duration,
+                ease: anim.ease,
+                properties: groupProperties,
+                fromProperties,
+                extras: anim.extras,
+            });
+            result = addResult.script;
+        }
+    }
+    // Re-parse to collect the new IDs.
+    const reParsed = parseGsapAst(result);
+    const newIds = reParsed.located
+        .filter((l) => l.animation.targetSelector === anim.targetSelector)
+        .map((l) => l.id);
+    return { script: result, ids: newIds };
+}
 /**
  * Replace a dynamic loop that generates multiple tween calls with individual
  * static `tl.to()` calls — one per element. Finds the loop containing the
@@ -1897,7 +2216,7 @@ export function unrollDynamicAnimations(script, animationId, elements) {
         if (el.easeEach) {
             kfEntries.push(`easeEach: ${JSON.stringify(el.easeEach)}`);
         }
-        calls.push(`tl.to(${JSON.stringify(el.selector)}, { keyframes: { ${kfEntries.join(", ")} }, duration: ${duration}, ease: ${JSON.stringify(ease)} }, ${posCode});`);
+        calls.push(`${loc.parsed.timelineVar}.to(${JSON.stringify(el.selector)}, { keyframes: { ${kfEntries.join(", ")} }, duration: ${duration}, ease: ${JSON.stringify(ease)} }, ${posCode});`);
     }
     const replacement = calls.join("\n  ");
     if (loopNode) {