@freestylejs/ani-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,653 @@
+interface TimingFunctionContext {
+    /**
+     * delta t
+     */
+    dt: number;
+    /**
+     * from value, initial position (`s(0)`)
+     */
+    from: number;
+    /**
+     * to value, original position (`s(f)`)
+     */
+    to: number;
+    /**
+     * animation duration, but it is not possible for specific functions
+     */
+    duration: number;
+    /**
+     * animation end tolerance
+     */
+    tolerance?: number;
+}
+declare abstract class TimingFunction {
+    /**
+     * Step function
+     * @param time Current time
+     * @param context Context for step calculation
+     */
+    abstract step(time: number, context: TimingFunctionContext): {
+        value: number;
+        endOfAnimation: boolean;
+    };
+    private static DEFAULT_TOLERANCE;
+    /**
+     * Checks whether the animation has ended.
+     *
+     * @param time - The current time.
+     * @param value - The computed value at the current time.
+     * @param context - The animation context.
+     * @returns {boolean} True if the animation is ended, false otherwise.
+     */
+    protected checkEnd(time: number, value: number, context: TimingFunctionContext, checkTimeOnly?: boolean): boolean;
+}
+interface Coord {
+    x: number;
+    y: number;
+}
+
+declare class LinearTimingFunction extends TimingFunction {
+    step(time: number, context: TimingFunctionContext): {
+        value: number;
+        endOfAnimation: boolean;
+    };
+}
+
+/** biome-ignore-all lint/style/noMagicNumbers: <>*/
+
+interface BezierTimingFunctionOpt {
+    p2: Coord;
+    p3: Coord;
+}
+declare class BezierTimingFunction extends TimingFunction {
+    readonly opt: {
+        p2: Coord;
+        p3: Coord;
+    };
+    constructor(opt: {
+        p2: Coord;
+        p3: Coord;
+    });
+    private readonly p1;
+    private readonly p4;
+    private _bezierFunction;
+    step(time: number, context: TimingFunctionContext): {
+        value: number;
+        endOfAnimation: boolean;
+    };
+}
+
+interface SpringTimingFunctionOpt {
+    /**
+     * Mass constant.
+     */
+    m: number;
+    /**
+     * Spring constant.
+     */
+    k: number;
+    /**
+     * Damping constant.
+     */
+    c: number;
+    /**
+     * End of spring animation threshold.
+     * @default 1e-3
+     */
+    tolerance?: number;
+}
+declare class SpringTimingFunction extends TimingFunction {
+    readonly opt: SpringTimingFunctionOpt;
+    constructor(opt: SpringTimingFunctionOpt);
+    step(time: number, context: TimingFunctionContext): {
+        value: number;
+        endOfAnimation: boolean;
+    };
+}
+
+/**
+ * Core timing functions
+ */
+declare const T: {
+    /**
+     * Creates a new Bezier timing function instance.
+     *
+     * @param {Bezier.BezierTimingFunctionOpt} opt - Options for configuring the Bezier curve.
+     * A new instance of BezierTimingFunction.
+     */
+    readonly bezier: (opt: BezierTimingFunctionOpt) => BezierTimingFunction;
+    /**
+     * Creates a new Spring timing function instance.
+     *
+     * @param {Spring.SpringTimingFunctionOpt} opt - Options for configuring the Spring timing function.
+     * A new instance of SpringTimingFunction.
+     */
+    readonly spring: (opt: SpringTimingFunctionOpt) => SpringTimingFunction;
+    /**
+     * Creates linear timing function instance.
+     */
+    readonly linear: () => LinearTimingFunction;
+};
+
+interface Animatable {
+    /**
+     * Update animation based on dt
+     * @param dt delta time
+     */
+    update(dt: number): void;
+}
+/**
+ * Animation clock interface, can be user-injected.
+ */
+interface AnimationClockInterface {
+    subscribe(animatable: Animatable): void;
+    unsubscribe(animatable: Animatable): void;
+}
+declare class AnimationClock implements AnimationClockInterface {
+    private subscribers;
+    private animationFrameId;
+    private lastTimestamp;
+    private maxDeltaTime;
+    protected static clock: AnimationClock;
+    /**
+     * Crete new clock(singleton)
+     * @param maxDeltaTime default maxDt = 100ms
+     * @returns clock
+     */
+    static create(maxDeltaTime?: number): AnimationClock;
+    private constructor();
+    subscribe(animatable: Animatable): void;
+    unsubscribe(animatable: Animatable): void;
+    private start;
+    private stop;
+    private tick;
+}
+
+declare const TransformFunctionMap: {
+    readonly rotate: {
+        readonly fn: "rotate";
+        readonly unit: "deg";
+    };
+    readonly rotateX: {
+        readonly fn: "rotateX";
+        readonly unit: "deg";
+    };
+    readonly rotateY: {
+        readonly fn: "rotateY";
+        readonly unit: "deg";
+    };
+    readonly rotateZ: {
+        readonly fn: "rotateZ";
+        readonly unit: "deg";
+    };
+    readonly skew: {
+        readonly fn: "skew";
+        readonly unit: "deg";
+    };
+    readonly skewX: {
+        readonly fn: "skewX";
+        readonly unit: "deg";
+    };
+    readonly skewY: {
+        readonly fn: "skewY";
+        readonly unit: "deg";
+    };
+    readonly translate: {
+        readonly fn: "translate";
+        readonly unit: "px";
+    };
+    readonly translateX: {
+        readonly fn: "translateX";
+        readonly unit: "px";
+    };
+    readonly translateY: {
+        readonly fn: "translateY";
+        readonly unit: "px";
+    };
+    readonly translateZ: {
+        readonly fn: "translateZ";
+        readonly unit: "px";
+    };
+    readonly scale: {
+        readonly fn: "scale";
+    };
+    readonly scaleX: {
+        readonly fn: "scaleX";
+    };
+    readonly scaleY: {
+        readonly fn: "scaleY";
+    };
+    readonly scaleZ: {
+        readonly fn: "scaleZ";
+    };
+};
+type TransformPropertiesLiteral = keyof typeof TransformFunctionMap;
+type PxPropertiesLiteral = 'width' | 'height' | 'margin' | 'marginTop' | 'marginBottom' | 'marginLeft' | 'marginRight' | 'padding' | 'paddingTop' | 'paddingBottom' | 'paddingLeft' | 'paddingRight' | 'top' | 'left' | 'right' | 'bottom' | 'borderWidth' | 'borderRadius';
+type UnitlessPropertiesLiteral = 'opacity' | 'zIndex' | 'lineHeight' | 'fontWeight';
+type StylesheetSupportedLiteral = TransformPropertiesLiteral | PxPropertiesLiteral | UnitlessPropertiesLiteral;
+type Resolver<T> = {
+    [Key in keyof T]?: (target: T[keyof T]) => {
+        key: string;
+        value: string | number;
+    };
+};
+type StylesheetValueTarget = Record<string, number>;
+declare function createStyleSheet(animeStyleValue: StylesheetValueTarget, resolver?: Resolver<StylesheetValueTarget>): Record<string, any>;
+
+type PartialRecord<K extends keyof any, T> = {
+    [P in K]?: T;
+};
+type Capitalize<T extends string> = T extends `${infer R}${infer Rest}` ? `${Uppercase<R>}${Rest}` : never;
+type WithPrefix<Prefix extends string, T extends string> = `${Prefix}${T}`;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type UnionToIntersection<Union> = (Union extends any ? (k: Union) => void : never) extends (k: infer I) => void ? I : never;
+type WithLiteral<Literal extends string> = Literal | (string & {});
+type WithLiteralRecord<Literal extends string, Value> = {
+    [key: string]: Value;
+} & {
+    [Key in Literal]?: Value;
+};
+
+type AnimePrimitive = readonly number[];
+type SegmentTiming = TimingFunction | readonly TimingFunction[];
+
+/**
+ * Animatable target values
+ */
+type Groupable = AnimePrimitive | GroupableRecord;
+type GroupableRecordKey = WithLiteral<StylesheetSupportedLiteral>;
+type GroupableRecord = WithLiteralRecord<GroupableRecordKey, AnimePrimitive[number]>;
+type AniGroup<G extends Groupable> = Prettify<UnionToIntersection<G>>;
+interface ExecutionSegment<G extends Groupable> {
+    /**
+     * Execution segment node
+     */
+    node: SegmentNode<G>;
+    /**
+     * Animation start time
+     */
+    startTime: number;
+    /**
+     * Animation end time
+     */
+    endTime: number;
+}
+type ExecutionPlan<G extends Groupable> = Array<ExecutionSegment<G>>;
+type TimelineStatus = 'IDLE' | 'PLAYING' | 'PAUSED' | 'ENDED';
+type OnUpdateCallback<G extends Groupable> = (current: {
+    state: AniGroup<G>;
+    status: TimelineStatus;
+}) => void;
+type ShouldKeepSymbol = 'keep';
+type Keyframe<G extends Groupable> = Array<G | ShouldKeepSymbol>;
+type Duration = Array<number | ShouldKeepSymbol>;
+interface TimelineStartingConfig<G extends Groupable, Ctx = any> {
+    /**
+     * Starting dynamic value.
+     */
+    from: AniGroup<G>;
+    /**
+     * Dynamic `from` values, if passed `keep` for specific index, keep original timeline config.
+     */
+    keyframes?: Keyframe<G>;
+    /**
+     * Dynamic `duration` values, if passed `keep` for specific index, keep original timeline config.
+     */
+    durations?: Duration;
+    /**
+     * Custom context definition during animation cycle.
+     */
+    context?: Ctx;
+    /**
+     * Animation repeat count.
+     *
+     * - if `Infinity` goes infinity repeat
+     */
+    repeat?: number;
+    /**
+     * Custom style property resolver.
+     *
+     * @example
+     * ```ts
+     * const timeline = a.timeline(...)
+     * timeline.play({
+     *    propertyResolver: {
+     *       'px': (pxValue) => { key: `top`, value: `${pxValue}px` }
+     *    }
+     * })
+     * ```
+     */
+    propertyResolver?: G extends AnimePrimitive ? never : Resolver<G>;
+}
+/**
+ * Public timeline controller
+ */
+interface TimelineController<G extends Groupable, Ctx = any> {
+    /**
+     * Play timeline
+     * @param config Timeline starting configuration
+     * @param canBeIntercepted if `true`, will play animation again even if already PLAYING.
+     */
+    play(config: TimelineStartingConfig<G, Ctx>, canBeIntercepted?: boolean): void;
+    /**
+     * Pause timeline
+     */
+    pause(): void;
+    /**
+     * Resume timeline
+     */
+    resume(): void;
+    /**
+     * Seek to target time
+     * @param time
+     */
+    seek(time: number): void;
+    /**
+     * Reset timeline
+     */
+    reset(): void;
+}
+declare class Timeline<G extends Groupable, Ctx = any> implements TimelineController<G, Ctx>, Animatable {
+    /**
+     * Animation construction root node.
+     */
+    protected readonly rootNode: AnimationNode<G>;
+    readonly duration: number;
+    private readonly _baseExecutionPlan;
+    private _currentExecutionPlan;
+    private readonly _clock;
+    private _masterTime;
+    private _status;
+    private _currentConfig;
+    /**
+     * Current animation running config.
+     */
+    get currentConfig(): TimelineStartingConfig<G, Ctx> | null;
+    private _state;
+    private _initialState;
+    private _repeatCount;
+    private _propertyKeyMap;
+    private _segmentStartStates;
+    private _onUpdateCallbacks;
+    constructor(
+    /**
+     * Animation construction root node.
+     */
+    rootNode: AnimationNode<G>, clock?: AnimationClockInterface);
+    /**
+     * Resolves a Group (like {x, y}) into keys and values.
+     */
+    private _resolveGroup;
+    /**
+     * Resolves the internal state (a number array) back into Group.
+     */
+    private _resolveStateToGroup;
+    /**
+     * Compile animation execution plan
+     */
+    private _constructExecutionPlan;
+    /**
+     * Calculates the exact state of the animation at point.
+     */
+    private _calculateStateAtTime;
+    private _resolveExecutionPlan;
+    private notify;
+    play(config: TimelineStartingConfig<G, Ctx>, canBeIntercepted?: boolean): void;
+    pause(): void;
+    resume(): void;
+    reset(notify?: boolean): void;
+    seek(targetTime: number): void;
+    getCurrentValue(): AniGroup<G> | null;
+    onUpdate(callback: OnUpdateCallback<G>): () => void;
+    update(dt: number): void;
+}
+declare function timeline<G extends Groupable, Ctx = any>(rootNode: AnimationNode<G>, clock?: AnimationClockInterface): Timeline<G, Ctx>;
+
+type AnimationId = string;
+type AnimationNodeType = string;
+type AnimationDuration = number;
+/**
+ * Nodes in the animation tree
+ */
+declare abstract class AnimationNode<G extends Groupable> {
+    abstract readonly type: AnimationNodeType;
+    abstract readonly duration: AnimationDuration;
+    readonly id?: AnimationId;
+    constructor(id?: AnimationId);
+    /**
+     * Constructs self node and its children into a flat execution plan.
+     * @param plan Execution plans to which segments will be added.
+     * @param startTime The absolute current start time for this node within the master timeline.
+     */
+    abstract construct(plan: ExecutionPlan<G>, startTime: number): void;
+}
+type ExtractAnimationNode<AnimeNode> = AnimeNode extends AnimationNode<infer Group> ? Group : never;
+
+type CompositionChildren = readonly AnimationNode<Groupable>[];
+type CompositionPlan<Children extends CompositionChildren> = ExecutionPlan<ExtractAnimationNode<Children[number]>>;
+/**
+ * Composition animation
+ */
+declare abstract class CompositionNode<const Children extends CompositionChildren> extends AnimationNode<ExtractAnimationNode<Children[number]>> {
+    /**
+     * Composition children nodes.
+     */
+    readonly children: Children;
+    constructor(children: Children, timing?: TimingFunction, id?: AnimationId);
+}
+
+interface SegmentNodeProps<G extends Groupable> {
+    readonly to: G;
+    readonly duration?: number;
+    readonly timing?: SegmentTiming;
+}
+/**
+ * Leaf node in the animation tree
+ */
+declare class SegmentNode<G extends Groupable> extends AnimationNode<G> {
+    readonly type = "SEGMENT";
+    readonly props: SegmentNodeProps<G>;
+    constructor(props: SegmentNodeProps<G>, id?: AnimationId);
+    get duration(): number;
+    construct(plan: ExecutionPlan<G>, startTime: number): void;
+}
+/**
+ * Factory function to create a ani SegmentNode.
+ */
+declare function ani<G extends Groupable>(props: SegmentNodeProps<G>, id?: AnimationId): SegmentNode<G>;
+
+type PreserveRecord = Record<string, any>;
+/**
+ * Creates a pause in an animation sequence.
+ * @param duration The duration of the delay in seconds.
+ * @param id Optional ID for the node.
+ */
+declare function delay(duration: number, id?: AnimationId): SegmentNode<PreserveRecord>;
+
+/**
+ * Composition node that repeats a child animation node a specified number of times.
+ */
+declare class LoopNode<G extends Groupable> extends CompositionNode<readonly AnimationNode<G>[]> {
+    readonly type = "LOOP";
+    readonly duration: number;
+    readonly count: number;
+    readonly child: AnimationNode<G>;
+    constructor(child: AnimationNode<G>, loopCount: number, timing?: TimingFunction, id?: AnimationId);
+    construct(plan: CompositionPlan<readonly AnimationNode<G>[]>, startTime: number): void;
+}
+/**
+ * Repeats a child animation node a specified number of times.
+ * @param child The animation node to repeat.
+ * @param loopCount The number of times to repeat the child node.
+ * @param timing loop timing function.
+ * @param id Optional ID for the node.
+ */
+declare function loop<G extends Groupable>(child: AnimationNode<G>, loopCount: number, timing?: TimingFunction, id?: AnimationId): LoopNode<G>;
+
+/**
+ * Composition node that runs all of its children at the same time.
+ */
+declare class ParallelNode<const Children extends CompositionChildren> extends CompositionNode<Children> {
+    readonly type = "PARALLEL";
+    readonly duration: number;
+    constructor(children: Children, timing?: TimingFunction, id?: AnimationId);
+    construct(plan: CompositionPlan<Children>, startTime: number): void;
+}
+/**
+ * Parallel composition animation
+ */
+declare function parallel<const Children extends CompositionChildren>(children: Children, timing?: TimingFunction, id?: AnimationId): ParallelNode<Children>;
+
+/**
+ * Composition node that runs its children one after another.
+ */
+declare class SequenceNode<const Children extends CompositionChildren> extends CompositionNode<Children> {
+    readonly type = "SEQUENCE";
+    readonly duration: number;
+    constructor(children: Children, timing?: TimingFunction, id?: AnimationId);
+    construct(plan: CompositionPlan<Children>, startTime: number): void;
+}
+/**
+ * Sequence composition animation
+ */
+declare function sequence<const Children extends CompositionChildren>(children: Children, timing?: TimingFunction, id?: AnimationId): SequenceNode<Children>;
+
+interface StaggerNodeProps {
+    offset: number;
+    timing?: TimingFunction;
+}
+/**
+ * Composition node that runs its children with a fixed delay between each start time.
+ */
+declare class StaggerNode<const Children extends CompositionChildren> extends CompositionNode<Children> {
+    readonly type = "STAGGER";
+    readonly duration: number;
+    readonly offset: number;
+    constructor(children: Children, props: StaggerNodeProps, id?: AnimationId);
+    construct(plan: CompositionPlan<Children>, startTime: number): void;
+}
+/**
+ * Stagger composition animation
+ */
+declare function stagger<const Children extends CompositionChildren>(children: Children, props: StaggerNodeProps, id?: AnimationId): StaggerNode<Children>;
+
+type AnimationStateShape = Record<string, AnimationNode<Groupable>>;
+type GetTimeline<State extends AnimationStateShape> = Timeline<ExtractAnimationNode<State[keyof State]>, any>;
+interface StateController<AnimationStates extends AnimationStateShape> {
+    /**
+     * Get current timeline.
+     */
+    timeline: () => GetTimeline<AnimationStates>;
+    /**
+     * Transition timeline animation into another state.
+     * @param newState transition target.
+     *
+     * @param timelineConfig animation play config.
+     * @param canBeIntercepted animation canBeIntercepted config.
+     */
+    transitionTo(newState: keyof AnimationStates, timelineConfig?: TimelineStartingConfig<ExtractAnimationNode<AnimationStates[keyof AnimationStates]>, any>, canBeIntercepted?: boolean): void;
+    /**
+     * Subscribe to timeline changes.
+     * @param callback
+     * @returns unsubscribe function
+     */
+    onTimelineChange(callback: (newTimeline: GetTimeline<AnimationStates>) => void): () => void;
+}
+interface StateProps<AnimationStates extends AnimationStateShape> {
+    /**
+     * Initial animation target state.
+     */
+    initial: keyof AnimationStates;
+    /**
+     * Initial animation `from` value.
+     */
+    initialFrom: AniGroup<ExtractAnimationNode<AnimationStates[keyof AnimationStates]>>;
+    /**
+     * Animating target states.
+     */
+    states: AnimationStates;
+    /**
+     * Custom timeline clock
+     */
+    clock?: AnimationClockInterface;
+}
+/**
+ * Creates a state machine controller for managing animations.
+ *
+ * @param config - The configuration for the state machine.
+ * @param clock - Optional custom animation clock.
+ * @returns A controller for managing the animation states.
+ */
+declare function createStates<AnimationStates extends AnimationStateShape>(config: StateProps<AnimationStates>): StateController<AnimationStates>;
+
+type EventHandler<AnimationContext = any, EvtKeys extends EventKey = EventKey> = (animationContext: AnimationContext, ev: HTMLElementEventMap[EvtKeys]) => any;
+type EventHandlerRegistration<AnimationContext = any, Keys extends EventKey = EventKey> = PartialRecord<WithPrefix<'on', Capitalize<Keys>>, EventHandler<AnimationContext, Keys>>;
+type EventKey = keyof HTMLElementEventMap;
+declare class EventManager<SupportedEventList extends readonly EventKey[] = EventKey[], AnimationContext = any> {
+    readonly supportedEvents: SupportedEventList;
+    constructor(supportedEvents: SupportedEventList);
+    private _element;
+    get targetElement(): HTMLElement;
+    private _animeGetter;
+    get animeGetter(): () => AnimationContext;
+    setAnimeGetter: (animeGetter: () => AnimationContext) => void;
+    private eventMap;
+    private withAnimeValue;
+    add: <const EventName extends SupportedEventList[number]>(eventName: EventName, listener: EventHandler<AnimationContext, SupportedEventList[number]>, options?: boolean | AddEventListenerOptions) => void;
+    cleanupOne: <const EventName extends SupportedEventList[number]>(eventName: EventName) => boolean;
+    cleanupAll: () => boolean;
+    /**
+     * get pure `{event_name}`
+     * @param key onX`{event_name}`
+     */
+    static getEvtKey(key: string): EventKey;
+    attach: (handlers: EventHandlerRegistration<AnimationContext, SupportedEventList[number]>) => void;
+    bind(element: HTMLElement): void;
+}
+
+type AniRefContext<G extends Groupable> = TimelineController<G> & {
+    /**
+     * Current animation value
+     */
+    current: AniGroup<G> | null;
+};
+interface AniRefProps<G extends Groupable, AsGetter extends boolean = false> {
+    /**
+     * The compositional timeline to bind to the element.
+     */
+    timeline: AsGetter extends true ? () => Timeline<G> : Timeline<G>;
+    /**
+     * The initial style to apply to the element before the animation plays.
+     */
+    initialValue?: AniGroup<G>;
+    /**
+     * Event handlers to attach to the element.
+     */
+    events?: EventHandlerRegistration<AniRefContext<G>>;
+    /**
+     * If `true`, all event listeners will be removed on cleanup.
+     *
+     * @default true
+     */
+    cleanupEvents?: boolean;
+}
+
+declare const a: {
+    readonly timing: {
+        readonly bezier: (opt: BezierTimingFunctionOpt) => BezierTimingFunction;
+        readonly spring: (opt: SpringTimingFunctionOpt) => SpringTimingFunction;
+        readonly linear: () => LinearTimingFunction;
+    };
+    readonly ani: typeof ani;
+    readonly createStates: typeof createStates;
+    readonly delay: typeof delay;
+    readonly loop: typeof loop;
+    readonly parallel: typeof parallel;
+    readonly sequence: typeof sequence;
+    readonly stagger: typeof stagger;
+    readonly timeline: typeof timeline;
+};
+
+export { type AniGroup, type AniRefContext, type AniRefProps, type Animatable, AnimationClock, type AnimationClockInterface, type AnimationDuration, type AnimationId, AnimationNode, type AnimationNodeType, type AnimationStateShape, CompositionNode, type Coord, type EventHandler, type EventHandlerRegistration, type EventKey, EventManager, type ExecutionPlan, type ExecutionSegment, type GetTimeline, type Groupable, type GroupableRecord, type GroupableRecordKey, LinearTimingFunction, type OnUpdateCallback, ParallelNode, type Resolver, SegmentNode, SequenceNode, StaggerNode, type StateController, type StateProps, type StylesheetSupportedLiteral, T, Timeline, type TimelineController, type TimelineStartingConfig, TimingFunction, type TimingFunctionContext, a, ani, createStates, createStyleSheet, delay, loop, parallel, sequence, stagger, timeline };