feature request - support dynamic spring and initial delay features

packages/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @freestylejs/ani-core
 
+## 1.1.0
+
+### Minor Changes
+
+- Support dynamic sptring feature and initial delay(MS) at core.
+
 ## 1.0.0
 
 ### Major Changes

packages/core/package.json

@@ -1,17 +1,22 @@
 {
     "name": "@freestylejs/ani-core",
     "author": "freestyle",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "description": "Core functionality for the Ani animation library.",
     "license": "MIT",
     "type": "module",
-    "keywords": ["animation", "core"],
+    "keywords": [
+        "animation",
+        "core"
+    ],
     "sideEffects": false,
     "private": false,
     "publishConfig": {
         "access": "public"
     },
-    "files": ["dist"],
+    "files": [
+        "dist"
+    ],
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.ts",

packages/core/src/ani/__tests__/timeline.test.ts

@@ -556,4 +556,153 @@ describe('Timeline Controller', () => {
             )
         })
     })
+
+    describe('Delay Behavior', () => {
+        it('should delay the start of the animation', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 0.5 * 1e3 })
+
+            // Initial state should be set immediately
+            expect(onUpdate).toHaveBeenCalledWith({
+                state: [0],
+                status: 'PLAYING',
+            })
+
+            // During the delay, state should not change
+            clock.tick(0.25)
+            expect(onUpdate).toHaveBeenCalledTimes(1) // No new updates
+
+            clock.tick(0.25) // Delay finishes
+            expect(onUpdate).toHaveBeenCalledTimes(1)
+
+            // After delay, animation starts
+            clock.tick(0.5) // Halfway through animation
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [50],
+                status: 'PLAYING',
+            })
+
+            clock.tick(0.5) // Animation finishes
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [100],
+                status: 'ENDED',
+            })
+        })
+
+        it('should handle a delay of zero correctly', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 0 * 1e3 }), clock.tick(0.5)
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [50],
+                status: 'PLAYING',
+            })
+        })
+
+        it('should pause and resume during the delay period', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 1 * 1e3 })
+
+            clock.tick(0.5) // Halfway through delay
+            line.pause()
+
+            // Tick while paused, nothing should happen
+            const callCount = onUpdate.mock.calls.length
+            clock.tick(1)
+            expect(onUpdate).toHaveBeenCalledTimes(callCount)
+
+            line.resume()
+            clock.tick(0.25) // Tick for half of the remaining delay
+            expect(onUpdate).toHaveBeenCalledTimes(callCount) // Still in delay
+
+            clock.tick(0.25) // Remaining delay finishes
+            clock.tick(0.5) // Animation is halfway
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [50],
+                status: 'PLAYING',
+            })
+        })
+
+        it('should reset correctly during the delay period', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 1 * 1e3 })
+            clock.tick(0.5)
+
+            line.reset()
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [],
+                status: 'IDLE',
+            })
+
+            // Ensure clock subscription is removed
+            const callCount = onUpdate.mock.calls.length
+            clock.tick(1)
+            expect(onUpdate).toHaveBeenCalledTimes(callCount)
+        })
+
+        it('should bypass the delay when seeking', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 1 * 1e3 })
+            line.seek(0.5)
+
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [50],
+                status: 'PAUSED',
+            })
+        })
+
+        it('should only apply the delay on the first run, not on repetitions', () => {
+            const root = ani({ to: [100], duration: 1, timing: linear })
+            const line = timeline(root, clock)
+            const onUpdate = vi.fn()
+            line.onUpdate(onUpdate)
+
+            line.play({ from: [0], delay: 0.5 * 1e3, repeat: 1 })
+
+            // Initial delay
+            clock.tick(0.5)
+
+            // First run
+            clock.tick(1)
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [100],
+                status: 'PLAYING',
+            })
+
+            line.play({
+                from: [0],
+                delay: 0 * 1e3,
+            })
+            expect(onUpdate).toHaveBeenCalledTimes(3) // tick(0.5) + tick(1) + play()
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [0],
+                status: 'PLAYING',
+            })
+
+            clock.tick(0.5)
+            expect(onUpdate).toHaveBeenLastCalledWith({
+                state: [50],
+                status: 'PLAYING',
+            })
+        })
+    })
 })

packages/core/src/ani/engine.ts

@@ -1,5 +1,6 @@
 import type { TimingFunction } from '~/timing'
 import { isEndOfAnimation } from '~/utils/time'
+import type { Groupable, GroupableRecord } from './timeline'
 
 export type AnimePrimitive = readonly number[]
 
@@ -10,7 +11,12 @@ export interface SegmentDefinition {
     timing: SegmentTiming
 }
 
-export type SegmentTiming = TimingFunction | readonly TimingFunction[]
+export type SegmentTiming<G extends Groupable = Groupable> =
+    G extends AnimePrimitive
+        ? readonly TimingFunction[] | TimingFunction
+        : G extends GroupableRecord
+          ? Record<keyof G, TimingFunction> | TimingFunction
+          : never
 
 export interface SegmentState {
     values: AnimePrimitive

packages/core/src/ani/nodes/segment.ts

@@ -4,8 +4,8 @@ import { type AnimationId, AnimationNode } from './base'
 
 export interface SegmentNodeProps<G extends Groupable> {
     readonly to: G
-    readonly duration?: number
-    readonly timing?: SegmentTiming
+    readonly duration: number
+    readonly timing?: SegmentTiming<G>
 }
 
 /**
@@ -19,14 +19,14 @@ export class SegmentNode<G extends Groupable> extends AnimationNode<G> {
         super(id)
         const nodeProps: SegmentNodeProps<G> = {
             to: props.to,
-            duration: props.duration ?? 0,
+            duration: props.duration,
             ...(props.timing !== undefined && { timing: props.timing }),
         }
         this.props = nodeProps
     }
 
-    get duration(): number {
-        return this.props.duration!
+    public get duration(): number {
+        return this.props.duration
     }
 
     public construct(plan: ExecutionPlan<G>, startTime: number): void {

packages/core/src/ani/timeline.ts

@@ -4,6 +4,7 @@ import {
     type AnimationClockInterface,
 } from '~/loop'
 import type { Resolver, StylesheetSupportedLiteral } from '~/style'
+import { TimingFunction } from '~/timing'
 import { isEndOfAnimation } from '~/utils/time'
 import type {
     Prettify,
@@ -83,6 +84,13 @@ export interface TimelineStartingConfig<G extends Groupable, Ctx = any> {
      */
     repeat?: number
 
+    /**
+     * Initial delay before animation starts.
+     *
+     * - unit = `MS`
+     */
+    delay?: number
+
     /**
      * Custom style property resolver.
      *
@@ -143,6 +151,8 @@ export class Timeline<G extends Groupable, Ctx = any>
 
     private _masterTime = 0
 
+    private _delay = 0
+
     private _status: TimelineStatus = 'IDLE'
     private _currentConfig: TimelineStartingConfig<G, Ctx> | null = null
     /**
@@ -264,11 +274,19 @@ export class Timeline<G extends Groupable, Ctx = any>
 
             // From value calculations
             let fromValues: Array<number> = []
+            const timings: Array<TimingFunction> = []
+            const t = segment.node.props.timing
+            const isRecordTiming: boolean = t && !(t instanceof TimingFunction)
+
             if (isRecordAni) {
                 for (const key of keyMap!.keys()) {
-                    fromValues.push(
-                        stateAtLastStartTime[this._propertyKeyMap!.get(key)!]!
-                    )
+                    const index = this._propertyKeyMap!.get(key)!
+                    fromValues.push(stateAtLastStartTime[index]!)
+                    if (isRecordTiming) {
+                        timings.push(
+                            (t as Record<string, TimingFunction>)[key]!
+                        )
+                    }
                 }
             } else {
                 fromValues = stateAtLastStartTime
@@ -282,7 +300,7 @@ export class Timeline<G extends Groupable, Ctx = any>
                 from: fromValues,
                 to: toValues,
                 duration: segment.node.duration,
-                timing: segment.node.props.timing,
+                timing: isRecordAni && isRecordTiming ? timings : t,
             }
 
             const segmentState = calculateSegmentState(
@@ -424,6 +442,10 @@ export class Timeline<G extends Groupable, Ctx = any>
         // update current config
         this._currentConfig = config
 
+        if (this._repeatCount === 0) {
+            this._delay = (this._currentConfig.delay ?? 0) * 1e-3 // MS
+        }
+
         this._currentExecutionPlan = this._resolveExecutionPlan(
             config.keyframes,
             config.durations
@@ -436,7 +458,7 @@ export class Timeline<G extends Groupable, Ctx = any>
 
         this._status = 'PLAYING'
         this._clock.subscribe(this)
-        this.update(0) // Render initial frame
+        this.notify()
     }
 
     public pause(): void {
@@ -456,6 +478,7 @@ export class Timeline<G extends Groupable, Ctx = any>
         this._currentConfig = null
 
         this._masterTime = 0
+        this._delay = 0
 
         this._state = []
         this._initialState = []
@@ -503,6 +526,16 @@ export class Timeline<G extends Groupable, Ctx = any>
             return
         }
 
+        if (this._delay > 0) {
+            this._delay -= dt
+            if (this._delay < 0) {
+                dt = -this._delay
+                this._delay = 0
+            } else {
+                return
+            }
+        }
+
         this._masterTime += dt
         if (this._masterTime >= this.duration) {
             this._masterTime = this.duration