idlize

1
/*
2
 * Copyright (c) 2022-2024 Huawei Device Co., Ltd.
3
 * Licensed under the Apache License, Version 2.0 (the "License");
4
 * you may not use this file except in compliance with the License.
5
 * You may obtain a copy of the License at
6
 *
7
 * http://www.apache.org/licenses/LICENSE-2.0
8
 *
9
 * Unless required by applicable law or agreed to in writing, software
10
 * distributed under the License is distributed on an "AS IS" BASIS,
11
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
 * See the License for the specific language governing permissions and
13
 * limitations under the License.
14
 */
15

16
import { float64, int64, uint32 } from "@koalaui/common"
17
import { RunEffect } from "../memo/changeListener"
18
import { remember } from "../memo/remember"
19
import { AnimatedState, ImplicitAnimationProvider, MutableAnimatedState, ParametrizedAnimationProvider, StateAnimator, animatedState, mutableAnimatedState, stateAnimator } from "./AnimatedState"
20
import { AnimationRange, NumberAnimationRange } from "./AnimationRange"
21
import { Easing, EasingCurve } from "./Easing"
22
import { AnimationSpec, TimeAnimation, animation, constAnimation, periodicAnimation, transition } from "./TimeAnimation"
23

24
/**
25
 * Function allowing to sample particular function with given rate.
26
 *
27
 * @param sampleRate number of milliseconds between samples
28
 * @param generator dirty function that produces values we interested in
29
 *
30
 * @returns value of generator function taken once in sampleRate ms
31
 * @memo
32
 */
33
export function sampledValue<V>(sampleRate: uint32, generator: (tick: int64) => V): V {
34
    return rememberAnimatedState(() => periodicAnimation(sampleRate, generator), true).value
35
}
36

37

38
/**
39
 * Creates and remembers animated state that could later be used as data source for animations.
40
 *
41
 * @param animation - supplier of the animation definition
42
 * @param startNow - if animation shall start immediately after creation
43
 * @returns animated state with the specified animation
44
 * @memo
45
 */
46
export function rememberAnimatedState<V>(animation: () => TimeAnimation<V>, startNow: boolean = false): AnimatedState<V> {
47
    return remember(() => animatedState(animation(), startNow))
48
}
49

50
/**
51
 * Creates and remembers number transition that could later be used as data source for animations.
52
 *
53
 * @param on - specifies the direction of the animation (false to 0, true to 1)
54
 * @param duration - duration of state transition from 0 to 1
55
 * @param easing - a way in which a motion tween proceeds
56
 * @param to - a target value that corresponds to the 1 state
57
 * @param from - a initial value that corresponds to the 0 state
58
 * @returns animated state with the specified transition
59
 * @memo
60
 */
61
export function rememberNumberTransition(on: boolean, duration: uint32, easing: EasingCurve = Easing.Linear, to: float64 = 1.0, from: float64 = 0.0): AnimatedState<float64> {
62
    return rememberTransition(on, duration, easing, NumberAnimationRange(from, to))
63
}
64

65
/**
66
 * Creates and remembers value transition that could later be used as data source for animations.
67
 * If it is needed to start the transition on appearing,
68
 * the `on` and `initial` parameters must have different values.
69
 *
70
 * @param on - specifies the direction of the animation (false to 0, true to 1)
71
 * @param duration - duration of state transition from 0 to 1
72
 * @param easing - a way in which a motion tween proceeds
73
 * @param compute - value supplier to be computed when state animated from 0 to 1
74
 * @param initial - initial state of the transition (false to 0, true to 1)
75
 * @returns animated state with the specified transition
76
 * @memo
77
 */
78
export function rememberTransition<Value>(on: boolean, duration: uint32, easing: EasingCurve, compute: AnimationRange<Value>, initial: boolean = on): AnimatedState<Value> {
79
    const state: AnimatedState<Value> = rememberAnimatedState(() => transition(duration, easing, compute, initial ? 1 : 0), on)
80
    RunEffect(!on, (paused) => state.paused = paused)
81
    return state
82
}
83

84

85
/**
86
 * Creates and remembers a mutable state that automatically animates the value as it changes.
87
 *
88
 * @param initial - initial value
89
 * @param animationProvider - factory producing a new animation from the current value and the target one
90
 * @returns a mutable state that automatically animates the value as it changes
91
 * @memo
92
 */
93
export function rememberMutableAnimatedState<Value>(initial: Value, animationProvider: ImplicitAnimationProvider<Value>): MutableAnimatedState<Value> {
94
    return remember(() => mutableAnimatedState(initial, animationProvider))
95
}
96

97
/**
98
 * Creates and remembers a mutable state that automatically animates the number value as it changes.
99
 *
100
 * @param initial - initial value
101
 * @param animationSpec - the animation specification that does not depend on changed values
102
 * @returns a mutable state that automatically animates the number value as it changes
103
 * @see rememberMutableAnimatedState
104
 * @memo
105
 */
106
export function rememberMutableAnimatedStateNumber(initial: float64, animationSpec: Partial<AnimationSpec>): MutableAnimatedState<float64> {
107
    return remember(() => mutableAnimatedState(initial, (from: float64, to: float64) => from == to
108
        ? constAnimation(to)
109
        : animation(animationSpec, NumberAnimationRange(from, to))))
110
}
111

112

113
/**
114
 * Creates and remembers state animator with controllable parameter.
115
 * When parameter is changed, the animation is recreated.
116
 *
117
 * @param parameter - initial value for controlling parameter
118
 * @param animationProvider - factory producing a new animation when parameter changed
119
 * @returns state animator with the animation created for given parameter
120
 * @memo
121
 */
122
export function rememberAnimator<P, V>(parameter: P, animationProvider: ParametrizedAnimationProvider<P, V>): StateAnimator<P, V> {
123
    return remember(() => stateAnimator(parameter, animationProvider))
124
}
125