@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/viewcontroller/ViewController.kt

@@ -0,0 +1,320 @@
+package dev.apexnative.navigation.viewcontrollers.viewcontroller
+
+import android.animation.Animator
+import android.app.Activity
+import android.view.ViewGroup
+import dev.apexnative.navigation.options.DefaultOptions
+import dev.apexnative.navigation.options.Options
+import dev.apexnative.navigation.options.OptionsCache
+import dev.apexnative.navigation.options.params.Bool
+import dev.apexnative.navigation.options.params.NullBool
+import dev.apexnative.navigation.react.CommandListener
+import dev.apexnative.navigation.react.ReloadCoordinator
+import dev.apexnative.navigation.viewcontrollers.parent.ParentController
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
+import java.lang.ref.WeakReference
+
+/**
+ * A node of the layout tree on Android: a screen, or a layout of nodes (a stack, tabs, a split view, a pair), with its
+ * id, its options and its view, made when it is first asked for. The native side owns the tree; commands find a node
+ * by id (`ChildControllersRegistry`). Main thread only.
+ *
+ * Members a module overrides are open.
+ */
+abstract class ViewController<V : ViewGroup>(
+    /** The activity the node's view lives in. */
+    val activity: Activity,
+    /** The node's id in the layout: the commands and the events name it. */
+    val id: String,
+    /** The options the layout was made with, one-shot options included. */
+    var initialOptions: Options,
+) {
+    /**
+     * The node's own options: those it was made with, with every `mergeOptions` and every user's choice over them.
+     * Writing them is one of the two places the options change ([OptionsCache]): the setter takes away the one-shot
+     * options, keeps the object (a stripped copy when it has a one-shot option: the caller's object never changes), and
+     * makes every resolved result stale. Don't change the object in place: [changeOptions] or [mergeOptions] write a
+     * changed copy.
+     */
+    var options: Options = initialOptions.copy().also(Options::clearOneShotOptions)
+        set(value) {
+            field = if (value.hasOneShotOptions()) value.copy().also(Options::clearOneShotOptions) else value
+            OptionsCache.optionsChanged()
+        }
+
+    /**
+     * The JavaScript the node was made for (`ReloadCoordinator`): the events of the node and its screens reach only
+     * that one.
+     */
+    internal val jsGeneration: Int = ReloadCoordinator.generation
+
+    private var createdView: V? = null
+    private var parent: ParentController<*>? = null
+    private val appearedListeners = mutableListOf<Runnable>()
+    private var waitForRender: Bool = NullBool()
+
+    // The last result of resolveCurrentOptions(DefaultOptions.current), the generation it was built at, and the nodes
+    // it was built along: the layouts around this node, and the chain of current children under it.
+    private var resolved: Options? = null
+    private var resolvedGeneration = -1L
+    private var resolvedAlong: List<WeakReference<ViewController<*>>> = emptyList()
+
+    /** The view is made. */
+    val isViewCreated: Boolean
+        get() = createdView != null
+
+    /** The node is destroyed: it shows nothing again. */
+    var isDestroyed = false
+        private set
+
+    /** The node's view, made now if it isn't yet; a destroyed node makes none ([getView]). */
+    val view: V
+        @JvmName("requireView") get() = getView()
+
+    /** The layout this node is in; none for a root, a modal's root, an overlay. */
+    var parentController: ParentController<*>?
+        get() = parent
+        @JvmName("assignParentController") set(value) = setParentController(value)
+
+    /** The node is the root of its window: no layout around it. */
+    val isRoot: Boolean
+        get() = parent == null
+
+    /** The node's view shows: it is made, in the window and visible with all its parents. */
+    open val isViewShown: Boolean
+        get() = !isDestroyed && createdView?.isShown == true
+
+    /**
+     * The node is the root of a modal shown as a sheet: the modals set it before the node's view is made, so its
+     * screens keep no room for the status bar from their first layout.
+     */
+    internal var shownAsSheet = false
+
+    /** The node is in a modal shown as a sheet: it keeps no room for the status bar. */
+    open val isInSheet: Boolean
+        get() = shownAsSheet || parent?.isInSheet == true
+
+    /**
+     * The node is in a side of a side menu (its left or right menu, not its center): the side goes the whole height of
+     * the window, and the node keeps no room for the status bar. The layout around answers for it
+     * (`ParentController.isInSideMenu(child)`).
+     */
+    open val isInSideMenu: Boolean
+        get() = parent?.isInSideMenu(this) == true
+
+    /** The name of the screen the node shows, without `slot:`; none for a layout of nodes. */
+    open val currentComponentName: String?
+        get() = null
+
+    /** Makes the node's view. */
+    protected abstract fun createView(): V
+
+    /**
+     * The node's view, made now if it isn't yet. A destroyed node makes no view: a view made then would take the place
+     * of a later node with the same id (a slot screen's container). Asking for it throws, which rejects the command
+     * that asked; a destroyed node is asked through [peekView].
+     */
+    fun getView(): V {
+        createdView?.let { return it }
+        check(!isDestroyed) { "the node '$id' is destroyed" }
+        return createView().also { createdView = it }
+    }
+
+    /** The node's view if it is made, without making it. */
+    fun peekView(): V? = createdView
+
+    open fun setParentController(parentController: ParentController<*>?) {
+        parent = parentController
+    }
+
+    /** Runs [task] with the layout this node is in, if it is in one. */
+    fun performOnParentController(task: (ParentController<*>) -> Unit) {
+        parent?.let(task)
+    }
+
+    /** The stack this node is in, up through the layouts around it; none out of a stack. */
+    fun findParentStack(): StackController? {
+        var current = parent
+        while (current != null) {
+            if (current is StackController) return current
+            current = current.parentController
+        }
+        return null
+    }
+
+    /**
+     * The node's options over those of the layouts around it, without the default options: the parents' resolution,
+     * then the node's own. A new object at each call, which the caller may change. For a layout of nodes this is not
+     * what it shows with: that is [resolveShownOptions].
+     */
+    open fun resolveCurrentOptions(): Options {
+        val resolved = parent?.resolveChildOptions(this) ?: Options()
+        return resolved.mergeWith(options)
+    }
+
+    /**
+     * The node's options over those of the layouts around it and [defaultOptions]: what it shows with. With the app's
+     * default options ([DefaultOptions.current]) the result is kept and given again while no options changed
+     * ([OptionsCache]) and the layouts around the node and its current children are the same: it is read-only, whoever
+     * changes it copies it first. Main thread only.
+     *
+     * For a layout of nodes (a stack, tabs, a side menu) it is the layout's own options over those around it, without
+     * any child's: not what the layout shows with, which [resolveShownOptions] gives.
+     */
+    open fun resolveCurrentOptions(defaultOptions: Options): Options {
+        if (defaultOptions !== DefaultOptions.current) return resolveCurrentOptions().withDefaultOptions(defaultOptions)
+        val generation = OptionsCache.generation
+        val along = resolvedAlong()
+        val kept = resolved
+        if (kept != null && resolvedGeneration == generation && sameNodes(along, resolvedAlong)) return kept
+        val result = resolveCurrentOptions().withDefaultOptions(defaultOptions)
+        resolved = result
+        resolvedGeneration = generation
+        resolvedAlong = along.map(::WeakReference)
+        return result
+    }
+
+    /**
+     * The options the node shows with, also at a moment that is not an appearance (a repaint, a merge into a hidden
+     * layout): for a screen its [resolveCurrentOptions]; for a layout of nodes those of the node at the end of its
+     * current-child chain, which hold the layout's own and every layout's between. A pair answers with its options
+     * screen (`OptionsScreen`). The result is [resolveCurrentOptions]'s of that node, kept and read-only in the same
+     * way. Main thread only.
+     */
+    open fun resolveShownOptions(defaultOptions: Options): Options = resolveCurrentOptions(defaultOptions)
+
+    // The layouts around this node, nearest first, then its current children down the visible chain.
+    private fun resolvedAlong(): List<ViewController<*>> {
+        val nodes = ArrayList<ViewController<*>>()
+        var up = parent
+        while (up != null) {
+            nodes += up
+            up = up.parentController
+        }
+        var down = (this as? ParentController<*>)?.currentChild
+        while (down != null) {
+            nodes += down
+            down = (down as? ParentController<*>)?.currentChild
+        }
+        return nodes
+    }
+
+    private fun sameNodes(nodes: List<ViewController<*>>, kept: List<WeakReference<ViewController<*>>>): Boolean =
+        nodes.size == kept.size && nodes.indices.all { nodes[it] === kept[it].get() }
+
+    /**
+     * Changes the node's own options: [change] gets a copy, which is stored ([options]). A presenter or a module that
+     * writes a user's choice into the options (a menu's checkmark, a search scope, tokens, a toggled button) does it
+     * this way; a button menu keeps its own shared `checked` (`ButtonMenuOptions`).
+     */
+    fun changeOptions(change: (Options) -> Unit) {
+        val copy = options.copy()
+        change(copy)
+        options = copy
+    }
+
+    /**
+     * `mergeOptions` with the node's id (`mergeOptions`): [options] go over its own and stay there (one-shot options
+     * not kept); what shows applies them ([applyMergedOptions], when the view shows; otherwise as it appears); the
+     * layouts around it apply their part (`ParentController.mergeChildOptions`, each passes it on). [options] still
+     * carry the one-shot options to them. Containers that hand the merge to a child override it.
+     */
+    open fun mergeOptions(options: Options) {
+        this.options = this.options.copy().mergeWith(options)
+        if (isViewShown) applyMergedOptions(options)
+        performOnParentController { it.mergeChildOptions(options, this) }
+    }
+
+    /** What [options] of a `mergeOptions` give applies over what shows; the node's view shows. */
+    protected open fun applyMergedOptions(options: Options) = Unit
+
+    /** The node shows with [options], resolved: they apply to its view and to the activity. */
+    open fun applyOptions(options: Options) = Unit
+
+    /** Calls [listener] each time the node has appeared, until it is removed. */
+    fun addOnAppearedListener(listener: Runnable) {
+        appearedListeners += listener
+    }
+
+    fun removeOnAppearedListener(listener: Runnable) {
+        appearedListeners -= listener
+    }
+
+    /** `waitForRender` of the node as it shows now: true holds it hidden until its content is drawn. */
+    fun setWaitForRender(waitForRender: Bool) {
+        this.waitForRender = waitForRender
+    }
+
+    /** A button of the bar over the node was pressed: the screen it shows sends `ANN.NavigationButtonPressed`. */
+    open fun sendOnNavigationButtonPressed(buttonId: String) = Unit
+
+    /**
+     * The animation of a push that brings this node in with [appearingOptions]; none for the default one. The stack
+     * plays its screens' animations itself, from the options of the node's options screen (a pair's are its
+     * primary's, the pair forwards these hooks to it), so nothing in the core asks here; the hook stays for the
+     * containers that answer it.
+     */
+    open fun getPushAnimations(appearingOptions: Options): Animator? = null
+
+    /** The animation of a pop that takes this node away; none for the default one. As [getPushAnimations]. */
+    open fun getPopAnimations(appearingOptions: Options, disappearingOptions: Options): Animator? = null
+
+    /** Back: the node goes back if it can, and tells [listener]; false when it has nothing to go back to. */
+    open fun handleBack(listener: CommandListener): Boolean = false
+
+    /** Whether [handleBack] would go back. */
+    open fun canHandleBack(): Boolean = false
+
+    /** Starts the node's content (a native screen's view, a React screen's surface). */
+    open fun start() = Unit
+
+    /**
+     * The node starts to appear: the layout that shows it, or the transition that brings it in, says so; a screen tells
+     * its appearance record (`AppearanceDispatcher`), a layout tells its visible children. A second call within one
+     * appearance tells nothing new.
+     */
+    open fun onViewWillAppear() = Unit
+
+    /**
+     * The node has appeared, as for [onViewWillAppear] (a screen whose appearance didn't start starts it first); then
+     * the listeners of [addOnAppearedListener] hear it.
+     */
+    open fun onViewDidAppear() {
+        appearedListeners.toList().forEach { it.run() }
+    }
+
+    /**
+     * The node has disappeared: it was covered or hidden, or it goes. A layout tells every child; a screen that didn't
+     * appear tells nothing. Nothing calls it when the activity goes to the background.
+     */
+    open fun onViewDisappear() = Unit
+
+    /** The node comes to the front again (a pop, a dismissed modal): what it set for the activity applies again. */
+    open fun onViewBroughtToFront() = Unit
+
+    /**
+     * The transition that takes the node away starts (a new root, a pop, a dismissed modal), before it is destroyed: a
+     * screen with `blurOnUnmount` lets go of the focus of the field it holds (`blurOnUnmount`). A layout tells every
+     * child.
+     */
+    open fun onLeaveStarted() = Unit
+
+    /** The room the node keeps at its top for what is over it: the status bar, a bar of the layouts around it. */
+    open fun getTopInset(): Int = parent?.getTopInset(this) ?: 0
+
+    /** Keeps the room of [getTopInset] at the node's top. */
+    open fun applyTopInset() = Unit
+
+    /** The room the node keeps at its bottom for what is under it: the tabs of the layouts around it. */
+    open fun getBottomInset(): Int = parent?.getBottomInset(this) ?: 0
+
+    /** Keeps the room of [getBottomInset] at the node's bottom. */
+    open fun applyBottomInset() = Unit
+
+    /** Destroys the node and its view; once. */
+    open fun destroy() {
+        if (isDestroyed) return
+        isDestroyed = true
+        appearedListeners.clear()
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/animations/AnimationRules.kt

@@ -0,0 +1,141 @@
+package dev.apexnative.navigation.views.animations
+
+import dev.apexnative.navigation.options.BottomTabsAnimationOptions
+import dev.apexnative.navigation.options.BottomTabsEnterExitAnimationOptions
+import dev.apexnative.navigation.options.ElementAnimationOptions
+import dev.apexnative.navigation.options.ElementTransitionOptions
+import dev.apexnative.navigation.options.EnterExitAnimationOptions
+import dev.apexnative.navigation.options.LayoutAnimation
+import dev.apexnative.navigation.options.ModalAnimationOptions
+import dev.apexnative.navigation.options.PropertyAnimationOptions
+import dev.apexnative.navigation.options.ScreenAnimationOptions
+import dev.apexnative.navigation.options.StackAnimationOptions
+import dev.apexnative.navigation.options.TopBarAnimationOptions
+import dev.apexnative.navigation.options.ViewAnimationOptions
+import dev.apexnative.navigation.options.params.Bool
+
+/**
+ * The rules of the `animations` options: which property plays, which side plays, when a command's animation is its own
+ * (the core plays it, not the platform's default), and how long a side lasts. The one place of these rules: the stack,
+ * the modals, the root and the bars ask here. Pure.
+ */
+internal object AnimationRules {
+    /** The duration of a property, an element or a shared element without its own, ms. */
+    const val DEFAULT_DURATION = 300L
+
+    /** The fade of a screen around elements without an animation of its own, ms. */
+    const val SCREEN_FADE = 300L
+
+    /** A property plays when it has `from` or `to`. */
+    fun propertyPlays(property: PropertyAnimationOptions): Boolean = property.from.hasValue() || property.to.hasValue()
+
+    /** An element's property plays when it has `from` or `to`. */
+    fun propertyPlays(property: ElementAnimationOptions): Boolean = property.from.hasValue() || property.to.hasValue()
+
+    /** The properties of [side] that play, in the order of the options. */
+    fun playingProperties(side: ViewAnimationOptions): List<PropertyAnimationOptions> =
+        properties(side).filter(::propertyPlays)
+
+    /** The ten properties of [side], in the order of the options. */
+    fun properties(side: ViewAnimationOptions): List<PropertyAnimationOptions> = listOf(
+        side.x, side.y, side.translationX, side.translationY, side.alpha, side.scaleX, side.scaleY, side.rotationX,
+        side.rotationY, side.rotation,
+    )
+
+    /**
+     * A side plays: it isn't turned off by `enabled: false` and at least one of its properties plays. An `enabled:
+     * false` side counts as no side.
+     */
+    fun sidePlays(side: ViewAnimationOptions?): Boolean {
+        side ?: return false
+        if (enabledOf(side)?.isFalse == true) return false
+        return properties(side).any(::propertyPlays)
+    }
+
+    /** A side is turned off (`enabled: false`): what it shows or hides goes at once. */
+    fun isTurnedOff(side: ViewAnimationOptions?): Boolean = side?.let(::enabledOf)?.isFalse == true
+
+    /**
+     * The side of a bar is given: it plays, or it is turned off. Either way the bar no longer goes with the screens of
+     * the system's transition (`animations.setStackRoot.bottomTabs.enter`).
+     */
+    fun barSideGiven(side: ViewAnimationOptions?): Boolean = sidePlays(side) || isTurnedOff(side)
+
+    /** The shared elements or the element transitions of [animation] are not empty. */
+    fun hasElements(animation: LayoutAnimation): Boolean =
+        animation.sharedElements.get().isNotEmpty() || animation.elementTransitions.transitions.isNotEmpty()
+
+    /**
+     * A transition of the stack is its own (push, pop, `setStackRoot`): `content.enter` or `content.exit` plays, or
+     * it has elements. `topBar`, `bottomTabs` and `zoom` never make it own.
+     */
+    fun stackIsOwn(animation: StackAnimationOptions): Boolean = contentIsOwn(animation) || hasElements(animation)
+
+    /** `content.enter` or `content.exit` of [animation] plays: what a push with `asPush` looks at. */
+    fun contentIsOwn(animation: StackAnimationOptions): Boolean =
+        sidePlays(animation.content.enter) || sidePlays(animation.content.exit)
+
+    /** A modal's show or dismissal is its own: `enter` or `exit` plays, or it has elements. */
+    fun modalIsOwn(animation: ModalAnimationOptions): Boolean =
+        sidePlays(animation.enter) || sidePlays(animation.exit) || hasElements(animation)
+
+    /** A new root's animation is its own: one of its sides plays. */
+    fun rootPlays(animation: EnterExitAnimationOptions): Boolean =
+        sidePlays(animation.enter) || sidePlays(animation.exit)
+
+    /**
+     * `showModal.enter.enabled: false` turns the whole show off; `waitForRender` alone keeps it.
+     */
+    fun showAnimated(animation: ModalAnimationOptions): Boolean = !animation.enter.enabled.isFalse
+
+    /** `dismissModal.exit.enabled: false` turns the whole dismissal off. */
+    fun dismissAnimated(animation: ModalAnimationOptions): Boolean = !animation.exit.enabled.isFalse
+
+    /** `setRoot.enter.enabled: false`: the root comes at once, whatever else is given. */
+    fun rootAtOnce(animation: EnterExitAnimationOptions): Boolean = animation.enter.enabled.isFalse
+
+    /**
+     * Android with elements takes the screen's own side only when it is a single `alpha`; else the screen fades by
+     * default.
+     */
+    fun isSingleAlpha(side: ViewAnimationOptions?): Boolean {
+        if (!sidePlays(side)) return false
+        val playing = playingProperties(requireNotNull(side) { "a side that plays is given" })
+        return playing.size == 1 && playing[0] === side.alpha
+    }
+
+    /** The side of a bar for its way: `enter` when it shows, `exit` when it hides. */
+    fun barSide(sides: BottomTabsEnterExitAnimationOptions?, showing: Boolean): BottomTabsAnimationOptions? =
+        sides?.let { if (showing) it.enter else it.exit }
+
+    // Length: what a shared element without a duration takes from a screen's single `alpha`.
+
+    /** Where a property ends after the start, ms: its delay and its duration, 300 without one. */
+    fun endOf(property: PropertyAnimationOptions): Long =
+        delayOf(property.startDelay.get(null)) + durationOf(property.duration.get(null), DEFAULT_DURATION)
+
+    /** Where [side] ends: the latest end of its playing properties; 0 when it doesn't play. */
+    fun lengthOf(side: ViewAnimationOptions?): Long =
+        if (!sidePlays(side)) 0L else playingProperties(requireNotNull(side) { "a side that plays is given" })
+            .maxOf(::endOf)
+
+    /** The ten properties of an element transition, in the order of the options. */
+    fun elementProperties(element: ElementTransitionOptions) = listOf(
+        element.x, element.y, element.translationX, element.translationY, element.alpha, element.scaleX,
+        element.scaleY, element.rotationX, element.rotationY, element.rotation,
+    )
+
+    /** A duration in ms from the options: unset, not finite or below 0 is [fallback]. */
+    fun durationOf(value: Double?, fallback: Long): Long =
+        if (value == null || !value.isFinite() || value < 0) fallback else value.toLong()
+
+    /** A delay in ms from the options: unset, not finite or below 0 is 0. */
+    fun delayOf(value: Double?): Long = durationOf(value, 0L)
+
+    private fun enabledOf(side: ViewAnimationOptions): Bool? = when (side) {
+        is ScreenAnimationOptions -> side.enabled
+        is TopBarAnimationOptions -> side.enabled
+        is BottomTabsAnimationOptions -> side.enabled
+        else -> null
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/views/animations/Curves.kt

@@ -0,0 +1,193 @@
+package dev.apexnative.navigation.views.animations
+
+import android.animation.TimeInterpolator
+import dev.apexnative.navigation.options.InterpolationOptions
+import kotlin.math.abs
+import kotlin.math.cos
+import kotlin.math.cosh
+import kotlin.math.exp
+import kotlin.math.pow
+import kotlin.math.round
+import kotlin.math.sin
+import kotlin.math.sinh
+import kotlin.math.sqrt
+
+/**
+ * A curve of `interpolation`: the part of the way f(p) at the part of the time p. Before the start it is exactly 0 and
+ * from the end on exactly 1, whatever the formula gives there: an animator's last frame is its target. Pure.
+ */
+internal abstract class Curve : TimeInterpolator {
+    /** f(p) for p in [0, 1]. */
+    protected abstract fun at(p: Double): Double
+
+    /** f(p): 0 at and before the start, 1 at and after the end. */
+    fun value(p: Double): Double = when {
+        p.isNaN() || p <= 0.0 -> 0.0
+        p >= 1.0 -> 1.0
+        else -> at(p)
+    }
+
+    override fun getInterpolation(input: Float): Float = value(input.toDouble()).toFloat()
+}
+
+/**
+ * The curves of `interpolation` by `type`, written from their formulas: the same values on iOS. A missing or unknown
+ * `type` is `linear`. The framework's curves are never used for the option (its `AccelerateDecelerateInterpolator` is a
+ * cosine, its `OvershootInterpolator` has another tension). Pure.
+ */
+internal object Curves {
+    /** The curve of [options] for a property that lasts [durationMillis]: a spring runs in real time. */
+    fun of(options: InterpolationOptions?, durationMillis: Long): Curve {
+        options ?: return Linear
+        return when (options.type.get(null)) {
+            "accelerate" -> Accelerate(factorOf(options))
+            "decelerate" -> Decelerate(factorOf(options))
+            "accelerateDecelerate" -> AccelerateDecelerate
+            "decelerateAccelerate" -> DecelerateAccelerate
+            "fastOutSlowIn" -> FastOutSlowIn
+            "overshoot" -> Overshoot(finite(options.tension.get(null)) ?: 1.0)
+            "spring" -> Spring(
+                mass = positive(options.mass.get(null)) ?: Spring.MASS,
+                damping = positive(options.damping.get(null)) ?: Spring.DAMPING,
+                stiffness = positive(options.stiffness.get(null)) ?: Spring.STIFFNESS,
+                allowsOverdamping = options.allowsOverdamping.isTrue,
+                initialVelocity = finite(options.initialVelocity.get(null)) ?: 0.0,
+                durationSeconds = durationMillis.coerceAtLeast(0L) / MILLIS,
+            )
+            else -> Linear
+        }
+    }
+
+    /** `linear`: f = p. */
+    object Linear : Curve() {
+        override fun at(p: Double): Double = p
+    }
+
+    /** `accelerate`: f = p^(2·factor). */
+    class Accelerate(private val factor: Double) : Curve() {
+        override fun at(p: Double): Double = p.pow(2 * factor)
+    }
+
+    /** `decelerate`: f = 1 − (1 − p)^(2·factor). */
+    class Decelerate(private val factor: Double) : Curve() {
+        override fun at(p: Double): Double = 1 - (1 - p).pow(2 * factor)
+    }
+
+    /** `accelerateDecelerate`: 4p³ before the middle, 1 − 4(1 − p)³ after it — slow at the ends. */
+    object AccelerateDecelerate : Curve() {
+        override fun at(p: Double): Double = if (p < HALF) 4 * p * p * p else 1 - 4 * (1 - p).pow(3)
+    }
+
+    /** `decelerateAccelerate`: 0.5 + 4(p − 0.5)³ — fast at the ends, still in the middle. */
+    object DecelerateAccelerate : Curve() {
+        override fun at(p: Double): Double = HALF + 4 * (p - HALF).pow(3)
+    }
+
+    /** `overshoot` with r = p − 1: 1 + r²((tension + 1)·r + tension) — past the target and back. */
+    class Overshoot(private val tension: Double) : Curve() {
+        override fun at(p: Double): Double {
+            val r = p - 1
+            return 1 + r * r * ((tension + 1) * r + tension)
+        }
+    }
+
+    /**
+     * `fastOutSlowIn`: the cubic Bézier (0.4, 0, 0.2, 1) sampled at x = i / 200 and rounded to 4 decimals, 201 values,
+     * linear between them — the values of AndroidX's `FastOutSlowInInterpolator`, computed here.
+     */
+    object FastOutSlowIn : Curve() {
+        /** The 201 values. */
+        val table: DoubleArray = DoubleArray(TABLE_STEPS + 1) {
+            round(bezierAt(it.toDouble() / TABLE_STEPS) * DECIMALS) / DECIMALS
+        }
+
+        override fun at(p: Double): Double {
+            val position = p * TABLE_STEPS
+            val index = position.toInt().coerceIn(0, TABLE_STEPS - 1)
+            val within = position - index
+            return table[index] + (table[index + 1] - table[index]) * within
+        }
+
+        /** y of the Bézier at its x = [x], exactly (to 1e-12). */
+        fun bezierAt(x: Double): Double {
+            if (x <= 0.0) return 0.0
+            if (x >= 1.0) return 1.0
+            // x(t) only grows with t: a bisection finds t, then y(t).
+            var low = 0.0
+            var high = 1.0
+            var t = x
+            repeat(BISECTION_STEPS) {
+                t = (low + high) / 2
+                if (bezier(t, X1, X2) < x) low = t else high = t
+            }
+            return bezier(t, Y1, Y2)
+        }
+
+        // One coordinate of the curve from (0, 0) to (1, 1) with the control points' coordinates [c1], [c2].
+        private fun bezier(t: Double, c1: Double, c2: Double): Double {
+            val u = 1 - t
+            return 3 * u * u * t * c1 + 3 * u * t * t * c2 + t * t * t
+        }
+
+        private const val X1 = 0.4
+        private const val Y1 = 0.0
+        private const val X2 = 0.2
+        private const val Y2 = 1.0
+        private const val BISECTION_STEPS = 60
+        private const val DECIMALS = 1e4
+    }
+
+    /**
+     * `spring`: a mass on a damped spring, m·x″ + c·x′ + k·x = 0 with x(0) = −1 and x′(0) = [initialVelocity] (parts of
+     * the way per second), at the real time t = p × the property's duration; f = 1 + x(t). ζ = c / 2m, ω₀ = √(k/m);
+     * without [allowsOverdamping] a damping over the critical one counts as the critical one.
+     */
+    class Spring(
+        mass: Double,
+        damping: Double,
+        stiffness: Double,
+        allowsOverdamping: Boolean,
+        private val initialVelocity: Double,
+        private val durationSeconds: Double,
+    ) : Curve() {
+        private val omega = sqrt(stiffness / mass)
+        private val zeta = (damping / (2 * mass)).let { if (!allowsOverdamping && it > omega) omega else it }
+
+        override fun at(p: Double): Double = 1 + distance(p * durationSeconds)
+
+        /** x(t): where the mass is at [t] seconds, −1 at the start and 0 at the target. */
+        fun distance(t: Double): Double {
+            val decay = exp(-zeta * t)
+            val gap = zeta * zeta - omega * omega
+            return when {
+                abs(gap) < CRITICAL_EPSILON -> decay * (-1 + (initialVelocity - zeta) * t)
+                gap < 0 -> {
+                    val damped = sqrt(-gap)
+                    decay * (-cos(damped * t) + (initialVelocity - zeta) / damped * sin(damped * t))
+                }
+                else -> {
+                    val over = sqrt(gap)
+                    decay * (-cosh(over * t) + (initialVelocity - zeta) / over * sinh(over * t))
+                }
+            }
+        }
+
+        companion object {
+            const val MASS = 3.0
+            const val DAMPING = 500.0
+            const val STIFFNESS = 200.0
+            private const val CRITICAL_EPSILON = 1e-9
+        }
+    }
+
+    private fun factorOf(options: InterpolationOptions): Double = finite(options.factor.get(null)) ?: 1.0
+
+    private fun finite(value: Double?): Double? = value?.takeIf { it.isFinite() }
+
+    // `mass`, `damping`, `stiffness` of 0 or less take their defaults.
+    private fun positive(value: Double?): Double? = finite(value)?.takeIf { it > 0 }
+
+    private const val HALF = 0.5
+    private const val MILLIS = 1000.0
+    private const val TABLE_STEPS = 200
+}