@pg-labs-incubator/cobweb 0.0.0-stage → 0.0.1

package/target/tsc/motion/transition.d.ts

@@ -0,0 +1,597 @@
+import type { Accessor, FlowComponent, JSX } from "solid-js";
+import type { MotionKeyframe, MotionOptions } from "./motion";
+import "./transition.css";
+/**
+ * Element which can be {@link Transition | transitioned} from or to.
+ *
+ * Transition elements may be either `undefined` or an DOM element. When transitioning from or to
+ * an `undefined` element, the transition applies only an enter or exit sequence, respectively.
+ */
+export type TransitionElement = Element | undefined;
+/**
+ * {@link Transition} target element tuple.
+ *
+ * A transition target is composed of two {@link TransitionElement | elements}, an exiting and
+ * entering element, respectively.
+ */
+export type TransitionTarget = [exiting: TransitionElement, entering: TransitionElement];
+/**
+ * Inline motion applied during a {@link Transition | transition}.
+ *
+ * Inline motions are defined by motion {@link MotionOptions | options} and {@link
+ * TransitionMotion.keyframes | keyframes}.
+ *
+ * @see {@link TransitionProps.enterMotion}
+ * @see {@link TransitionProps.exitMotion}
+ */
+export interface TransitionMotion extends MotionOptions {
+    /**
+     * Motion {@link MotionKeyframe | keyframe} array or keyframe array provider.
+     *
+     * This may be assigned to either a keyframe array or a keyframe array provider function.
+     * When assigned to a provider function, the function is invoked, with the transition
+     * {@link TransitionTarget | target}, when the respective sequence begins, and is expected
+     * to return a keyframe array to apply. If the keyframe array assigned, or provided, has a
+     * length of `0`, inline motion is not applied.
+     */
+    keyframes: ((target: TransitionTarget) => readonly MotionKeyframe[]) | readonly MotionKeyframe[];
+}
+/**
+ * {@link TransitionProps.children | Element} has changed and a new transition is beginning.
+ *
+ * This is entered into immediately before the enter or exit sequence of the transition
+ * begins.
+ *
+ * @see {@link TransitionState}
+ */
+export declare const TransitionBegin = 0;
+/**
+ * Enter sequence of transition has begun.
+ *
+ * This is entered into once the enter sequence of the transition begins, *after* {@link
+ * TransitionProps.enterClass | `props.enterClass`} and {@link TransitionProps.enterStartClass |
+ * `props.enterStartClass`} are applied to the entering element, but *before* {@link
+ * TransitionProps.enterMotionClass | `props.enterMotionClass`} or {@link
+ * TransitionProps.enterMotion | `props.enterMotion`} are applied to the entering element.
+ *
+ * @remarks
+ * This state is never entered into if the entering element is `undefined`.
+ * @see {@link TransitionState}
+ */
+export declare const EnterSequenceBegin = 1;
+/**
+ * Enter sequence of transition is ending.
+ *
+ * This is entered into immediately before the enter motion of the transition ends, *before*
+ * {@link TransitionProps.enterClass | `props.enterClass`} is removed from the entering element,
+ * but *after* {@link TransitionProps.enterMotionClass | `props.enterMotionClass`} is removed
+ * from the entering element.
+ *
+ * @remarks
+ * This state is never entered into if the entering element is `undefined`.
+ * @see {@link TransitionState}
+ */
+export declare const EnterSequenceEnd = 2;
+/**
+ * Exit sequence of transition has begun.
+ *
+ * This is entered into once the exit sequence of the transition begins, *after* {@link
+ * TransitionProps.exitClass | `props.exitClass`} and {@link TransitionProps.exitStartClass |
+ * `props.exitStartClass`} are applied to the exiting element, but *before* {@link
+ * TransitionProps.exitMotionClass | `props.exitMotionClass`} or {@link
+ * TransitionProps.exitMotion | `props.exitMotion`} are applied to the exiting element.
+ *
+ * @remarks
+ * This state is never entered into if the exiting element is `undefined`.
+ * @see {@link TransitionState}
+ */
+export declare const ExitSequenceBegin = 3;
+/**
+ * Exit sequence of transition is ending.
+ *
+ * This is entered into immediately before the exit motion of the transition ends, *before* {@link
+ * TransitionProps.exitClass | `props.exitClass`} is removed from the exiting element, but *after*
+ * {@link TransitionProps.exitMotionClass | `props.exitMotionClass`} is removed from the exiting
+ * element.
+ *
+ * @remarks
+ * This state is never entered into if the exiting element is `undefined`.
+ * @see {@link TransitionState}
+ */
+export declare const ExitSequenceEnd = 4;
+/**
+ * Transition has completed.
+ *
+ * This is entered into immediately after both the enter and exit sequences of the
+ * transition have ended.
+ *
+ * @see {@link TransitionState}
+ */
+export declare const TransitionEnd = 5;
+/**
+ * Union of {@link Transition | transition} states.
+ *
+ * @see {@link TransitionProps.onStateChange}
+ */
+export type TransitionState = typeof EnterSequenceBegin | typeof EnterSequenceEnd | typeof ExitSequenceBegin | typeof ExitSequenceEnd | typeof TransitionBegin | typeof TransitionEnd;
+/**
+ * Element {@link Transition | transition} component properties.
+ */
+export interface TransitionProps {
+    /**
+     * Transition name.
+     *
+     * This serves as the base name for the default values of CSS class properties, such as
+     * {@link TransitionProps.enterClass | `enterClass`}.
+     *
+     * @defaultValue `"cw-transition"`
+     */
+    name?: string;
+    /**
+     * CSS class applied to entering element during enter sequence.
+     *
+     * The class specified is applied to the entering element when the enter sequence begins,
+     * *before* the element is rendered into the DOM. The class is removed when the enter
+     * sequence ends. This may be used to apply styles which are present on the entering
+     * element for the entire duration of the enter sequence.
+     *
+     * @defaultValue `${props.name}-enter`
+     * @see {@link TransitionProps.enterMotionClass}
+     * @see {@link TransitionProps.enterStartClass}
+     */
+    enterClass?: string | readonly string[];
+    /**
+     * CSS class applied to entering element during enter sequence initialization.
+     *
+     * The class specified is applied to the entering element when the enter sequence begins,
+     * *before* the element is rendered into the DOM. The class is removed when the enter
+     * motion begins. This may be used to apply styles which the entering element is
+     * initialized with, but should not exist when enter motion begins.
+     *
+     * @defaultValue `${props.name}-enterStart`
+     * @see {@link TransitionProps.enterClass}
+     * @see {@link TransitionProps.enterMotionClass}
+     */
+    enterStartClass?: string | readonly string[];
+    /**
+     * CSS class applied to entering element after enter sequence initialization.
+     *
+     * The class specified is applied to the entering element after it has been rendered into
+     * the DOM, *after* {@link TransitionProps.enterStartClass | `enterStartClass`} is removed
+     * from the element. This class should be used to apply the enter motion.
+     *
+     * @defaultValue `${props.name}-enterMotion`
+     * @see {@link TransitionProps.enterClass}
+     * @see {@link TransitionProps.enterStartClass}
+     */
+    enterMotionClass?: string | readonly string[];
+    /**
+     * Inline motion {@link applyMotion | applied} to entering element after enter sequence
+     * initialization.
+     *
+     * The motion specified, if any, is applied to the entering element after it has been
+     * rendered into the DOM, *before* {@link TransitionProps.enterStartClass |
+     * `enterStartClass`} and {@link TransitionProps.enterMotionClass |
+     * `enterMotionClass`} is removed and applied to the element, respectively.
+     */
+    enterMotion?: Readonly<TransitionMotion>;
+    /**
+     * CSS class applied to exiting element during exit sequence.
+     *
+     * The class specified is applied to the exiting element when the exit sequence begins.
+     * The class is removed when the exit sequence ends. This may be used to apply styles
+     * which are present on the exiting element for the entire duration of the exit sequence.
+     *
+     * The default `cw-transition-exit` class, applied when {@link TransitionProps.name |
+     * `name`} and this property are omitted or `undefined`, disables interaction with the
+     * exiting element by setting `touch-action`, `user-select`, and `pointer-events` to
+     * `none`.
+     *
+     * @defaultValue `${props.name}-exit`
+     * @see {@link TransitionProps.exitMotionClass}
+     * @see {@link TransitionProps.exitStartClass}
+     */
+    exitClass?: string | readonly string[];
+    /**
+     * CSS class applied to exiting element during exit sequence initialization.
+     *
+     * The class specified is applied to the exiting element when the exit sequence begins.
+     * The class is removed when the exit motion begins. This may be used to apply styles
+     * which the exiting element is initialized with, but should not exist when the exit motion
+     * begins.
+     *
+     * @defaultValue `${props.name}-exitStart`
+     * @see {@link TransitionProps.exitClass}
+     * @see {@link TransitionProps.exitMotionClass}
+     */
+    exitStartClass?: string | readonly string[];
+    /**
+     * CSS class applied to exiting element after exit sequence initialization.
+     *
+     * The class specified is applied to the exiting element after {@link
+     * TransitionProps.exitStartClass | `exitStartClass`} is removed from the element, after
+     * the render frame in which `exitStartClass` is applied to the element. This class should
+     * be used to apply the exit motion.
+     *
+     * @defaultValue `${props.name}-exitMotion`
+     * @see {@link TransitionProps.exitClass}
+     * @see {@link TransitionProps.exitStartClass}
+     */
+    exitMotionClass?: string | readonly string[];
+    /**
+     * Inline motion {@link applyMotion | applied} to exiting element after exit sequence
+     * initialization.
+     *
+     * The motion specified, if any, is applied to the exiting element in the *same* frame in
+     * which {@link TransitionProps.exitStartClass | `exitStartClass`} is applied to the
+     * element, but *before* {@link TransitionProps.exitMotionClass | `exitMotionClass`} is
+     * applied to the element.
+     *
+     * Unless the motion specifies a {@link MotionOptions.fill | fill} of its own, it fills
+     * `"forwards"`, holding its end state until the exiting element is removed from the DOM; the
+     * motion is cancelled once the element is removed. An exiting element has no resting state to
+     * return to, but it stays in the DOM after its motion ends, while the exit sequence waits for
+     * a paint, for the other motions of the element, and for {@link
+     * TransitionProps.onStateChange | `onStateChange`}: without the hold, it would be drawn at
+     * rest meanwhile, such as for the frames after a motion which reduced motion ends at once.
+     */
+    exitMotion?: Readonly<TransitionMotion>;
+    /**
+     * Order of enter and exit sequences.
+     *
+     * This may be set to `"enter-exit"`, `"exit-enter"`, or `"parallel"` for exit sequence
+     * beginning *after* enter sequence is complete, enter sequence beginning *after* exit
+     * sequence is complete or, both enter and exit sequences beginning in parallel,
+     * respectively.
+     *
+     * @defaultValue `"parallel"`
+     */
+    order?: "enter-exit" | "exit-enter" | "parallel";
+    /**
+     * Apply enter sequence to initial entering element.
+     *
+     * When `true`, the enter sequence will be applied to the initial entering element if,
+     * and only if, it is not `undefined`.
+     *
+     * @defaultValue `false`
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly appear?: boolean;
+    /**
+     * Entering element.
+     *
+     * This may be assigned to either an element {@link Accessor | accessor} or an element.
+     * When assigned to an accessor, the accessor is invoked, in a reactive context, to
+     * determine when a transition should begin. When assigned to an element, however, the
+     * element is returned as-is without any transitions. If {@link TransitionProps.appear |
+     * `appear`} is `true`, however, and this is assigned to an element, the enter sequence is
+     * started for the element on initialization.
+     *
+     * As the return value of the accessor is updated, the previously rendered element, if any,
+     * is exited from, and the newly returned element, if any, is entered into. If the accessor
+     * returns the same element across two serial invocations, no transition is applied.
+     *
+     * @remarks
+     * This is **not** reactive; however, if an accessor is specified, the accessor may be
+     * reactive.
+     */
+    readonly children: Accessor<JSX.Element> | JSX.Element;
+    /**
+     * Callback invoked when transition {@link TransitionState | state} changes.
+     *
+     * This is invoked with the transition {@link TransitionTarget | target} and new state,
+     * respectively. This may return nothing or a promise which resolves to nothing. If a
+     * promise is returned, the transition will not progress forward until the promise is
+     * complete. If this function fails with an error, transition is aborted, and the entering
+     * element, if any, is entered into the DOM immediately.
+     *
+     * @param target - elements participating in this transition
+     * @param state - newly entered transition state
+     * @returns optional promise to await before advancing the transition; resolved values are
+     * ignored
+     *
+     * @remarks
+     * This is **not** reactive.
+     */
+    readonly onStateChange?: (target: TransitionTarget, state: TransitionState) => Promise<unknown> | unknown;
+}
+/**
+ * Component which transitions between two elements.
+ *
+ * This renders an element which transitions between the element {@link TransitionProps.children |
+ * `props.children`} evaluates to, and the previous element `props.children` evaluated to. Note
+ * that `props.children` may not be reactive, instead, it may be assigned to either an {@link
+ * TransitionElement | transition} element or an {@link Accessor | accessor} which returns a
+ * transition element.
+ *
+ * While most transition properties are reactive, it is important to note that when a transition
+ * begins, a snapshot of the transition properties is created. This snapshot of property values
+ * is used for the duration of the respective transition. Any updates to property values, while
+ * a transition is pending, the property will not be applied to that transition, instead it will
+ * be applied to the *next* transition.
+ *
+ * # `props.children`
+ *
+ * When `props.children` is a transition element, an enter sequence is applied to the transition
+ * element if, and only if, {@link TransitionProps.appear | `props.appear`} is `true` and the
+ * transition element is not `undefined`. In either case, the transition element is returned
+ * immediately.
+ *
+ * An accessor function `props.children`, however, is invoked in a tracking context. The initial
+ * rendered element is the initial return value of `props.children`. Any subsequent update of the
+ * accessor function results in a transition if, and only if, the updated element is not equal to
+ * the previously returned element. The enter sequence is entered into for the initial return
+ * value of `props.children` if `props.appear` is `true`; otherwise, only during an element update
+ * is a transition applied.
+ *
+ * ```tsx
+ * // An element which appears only once when created.
+ * <Transition appear={true} name="my-transition-name">
+ *     <div>Appears Once</div>
+ * </Transition>
+ *
+ * // An element which transitions between different elements reactively, and the initial element
+ * // has no enter sequence.
+ * <Transition name="my-transition-name">
+ *     <Switch>
+ *         <Match when={value() === "a"}>
+ *             <div>A</div>
+ *         </Match>
+ *         <Match when={value() === "b"}>
+ *             <div>B</div>
+ *         </Match>
+ *     </Switch>
+ * </Transition>
+ *
+ * // An element which transitions between different elements reactively, and the initial element
+ * // has an enter sequence.
+ * <Transition appear={true} name="my-transition-name">
+ *     <Switch>
+ *         <Match when={value() === "a"}>
+ *             <div>A</div>
+ *         </Match>
+ *         <Match when={value() === "b"}>
+ *             <div>B</div>
+ *         </Match>
+ *     </Switch>
+ * </Transition>
+ * ```
+ *
+ * # Transition
+ *
+ * Transition components maintain an internal state tracking the last entered element. As the
+ * `props.children` function updates its return value, the new return value is considered the
+ * entering element, while the last entered element is considered the exiting element. If
+ * `props.children` returns the last entered element, a transition is *not* initiated. In other
+ * words, the return value of `props.children` must be materially different from the last entered
+ * element, for a transition to begin.
+ *
+ * The last entered element, upon construction, is equal to the return value of `props.children`
+ * during component initialization. When {@link TransitionProps.appear | `props.appear`} is
+ * `true`, the last entered element is `undefined`, and the initial value of `props.children` is
+ * the entering element.
+ *
+ * Transitions stack, as such, if a transition is pending, and `props.children` is updated, then
+ * the new transition, if any, will be queued to begin *after* the pending transition completes.
+ * One exception to this is if `props.children` is updated to an element which already has a
+ * transition queued. In this case, all transitions succeeding the respective queued transition
+ * will be removed.
+ *
+ * A transition has at most two sequences, an enter sequence and an exit sequence. The enter and
+ * exit sequences are responsible for adding the entering element into the DOM and removing the
+ * exiting element from the DOM, respectively. If the entering or exiting element is not
+ * `undefined`, then the transition has an enter or exit sequence, respectively.
+ *
+ * The order of enter and exit sequence can be controlled using {@link TransitionProps.order |
+ * `props.order`}. When `props.order` is `"enter-exit"`, `"exit-enter"`, or, `"parallel"` or
+ * `undefined`, the exit sequence begins after the enter sequence ends, the enter sequence begins
+ * after the exit sequence ends, or both sequences start in parallel, respectively. Transition and
+ * sequence events can be consumed by specifying a {@link TransitionProps.onStateChange |
+ * `props.onStateChange`}.
+ *
+ * # Enter Sequence
+ *
+ * A transition will have an enter sequence if, and only if, the entering element is not
+ * `undefined`. The enter sequence is responsible for initializing the entering element for the
+ * enter motion, rendering the entering element into the DOM, awaiting enter motion completion,
+ * and removing enter motion styling from the element.
+ *
+ * When an enter sequence begins, it first applies {@link TransitionProps.enterClass |
+ * `props.enterClass`} and {@link TransitionProps.enterStartClass | `props.enterStartClass`} to
+ * the entering element. The `props.enterClass` is guaranteed to exist on the entering element
+ * for the duration of the enter sequence. The `props.enterStartClass`, however, exists on the
+ * entering element *only* until {@link TransitionProps.enterMotionClass |
+ * `props.enterMotionClass`} is applied to the element.
+ *
+ * After applying initial CSS classes to the entering element, the entering element is rendered
+ * into the DOM. After, the element is entered into the DOM, any {@link
+ * TransitionProps.enterMotion | inline} enter motion specified is {@link applyMotion | applied}
+ * to the entering element.
+ *
+ * Before `props.enterStartClass` is replaced with `props.enterMotionClass`, the enter sequence
+ * waits until the next paint frame. This barrier ensures the browser renders the styling from
+ * `props.enterStartClass` or `props.enterClass` *before* `props.enterMotionClass` is applied.
+ * Through this, `props.enterMotionClass` may initiate motions to a resting state with a
+ * guaranteed initial state, provided by `props.enterClass` or `props.enterStartClass`.
+ *
+ * This barrier is not required for the inline motion, as the inline motion utilizes the Web
+ * Animation API, which synchronizes the inline motion with the rendering pipeline of the
+ * browser.
+ *
+ * After `props.enterMotionClass` is applied, all motions pending on the entering element,
+ * including its recursively nested children and pseudo elements, are awaited on *before* ending
+ * the enter sequence. Note that motions whose timeline is not `document.timeline`, or whose
+ * iterations are infinite are ignored. Once pending motions are complete,
+ * `props.enterMotionClass` and `props.enterClass` are removed from the entering element.
+ *
+ * ```
+ *                                         +----------------+
+ *                                         | Begin Sequence |
+ *                                         +----------------+
+ *                                                 |
+ *                                                 v
+ *                          +-------------------------------------------------+
+ *                          | Add `props.enterStartClass`, `props.enterClass` |
+ *                          +-------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                                   +-----------------------------+
+ *                                   | Add entering element to DOM |
+ *                                   +-----------------------------+
+ *                                                 |
+ *                                                 v
+ *                    +-------------------------------------------------------------------+
+ *                    | 1. Invoke `props.onStateChange` with `EnterSequenceBegin`         |
+ *                    | 2. Start `props.enterMotion`                                      |
+ *                    +-------------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                              +----------------------------------------+
+ *                              | Wait until entering element is painted |
+ *                              +----------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                    +---------------------------------------------------------------+
+ *                    | Replace `props.enterStartClass` with `props.enterMotionClass` |
+ *                    +---------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *          +----------------------------------------------------------------------------------+
+ *          | Wait until all motions for entering element, including nested elements, complete |
+ *          +----------------------------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                  +-----------------------------------------------------------------+
+ *                  | 1. Remove `props.enterMotionClass`                              |
+ *                  | 2. Invoke `props.onStateChange` with `EnterSequenceEnd`         |
+ *                  +-----------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                                  +---------------------------+
+ *                                  | Remove `props.enterClass` |
+ *                                  +---------------------------+
+ *                                                 |
+ *                                                 v
+ *                                         +--------------+
+ *                                         | End Sequence |
+ *                                         +--------------+
+ * ```
+ *
+ * # Exit Sequence
+ *
+ * A transition will have an exit sequence if, and only if, the exiting element is not `undefined`.
+ * The exit sequence is responsible for initializing the exiting element for the exit motion,
+ * awaiting exit motion completion, removing exit motion styling from the element, and removing the
+ * element from the DOM.
+ *
+ * When an exit sequence begins, it first applies {@link TransitionProps.exitClass |
+ * `props.exitClass`} and {@link TransitionProps.exitStartClass | `props.exitStartClass`} to the
+ * exiting element. The `props.exitClass` is guaranteed to exist on the exiting element for the
+ * duration of the exit sequence. The `props.exitStartClass`, however, exists on the exiting
+ * element *only* until {@link TransitionProps.exitMotionClass | `props.exitMotionClass`} is
+ * applied to the element. After applying initial CSS classes to the exiting element, the {@link
+ * TransitionProps.exitMotion | inline} exit motion specified is {@link applyMotion | applied}
+ * to the exiting element. Unless it specifies a fill of its own, the inline exit motion holds its
+ * end state until the exiting element is removed from the DOM.
+ *
+ * Before `props.exitStartClass` is replaced with `props.exitMotionClass`, the exit sequence
+ * waits until the next paint frame. This barrier ensures the browser renders the styling from
+ * `props.exitStartClass` or `props.exitClass` *before* `props.exitMotionClass` is applied.
+ * Through this, `props.exitMotionClass` may initiate motions to a resting state with a guaranteed
+ * initial state, provided by `props.exitClass` or `props.exitStartClass`.
+ *
+ * This barrier is not required for the inline motion, as the inline motion utilizes the Web
+ * Animation API, which synchronizes the inline motion with the rendering pipeline of the
+ * browser.
+ *
+ * After `props.exitMotionClass` is applied, all motions pending on the exiting element, including
+ * its recursively nested children and pseudo elements, are awaited on *before* continuing the
+ * exit sequence. Note that motions whose timeline is not `document.timeline`, or whose iterations
+ * are infinite are ignored. Once pending motions are complete, `props.exitMotionClass` and
+ * `props.exitClass` are removed from the exiting element, the exiting element is removed from the
+ * DOM, and the inline exit motion is cancelled, so the element is at rest if it enters again.
+ *
+ * ```
+ *                                         +----------------+
+ *                                         | Begin Sequence |
+ *                                         +----------------+
+ *                                                 |
+ *                                                 v
+ *                          +-----------------------------------------------+
+ *                          | Add `props.exitStartClass`, `props.exitClass` |
+ *                          +-----------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                    +------------------------------------------------------------------+
+ *                    | 1. Invoke `props.onStateChange` with `ExitSequenceBegin`         |
+ *                    | 2. Start `props.exitMotion`, holding its end state               |
+ *                    +------------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                              +----------------------------------------+
+ *                              | Wait until exiting element is painted  |
+ *                              +----------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                    +-------------------------------------------------------------+
+ *                    | Replace `props.exitStartClass` with `props.exitMotionClass` |
+ *                    +-------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *          +----------------------------------------------------------------------------------+
+ *          | Wait until all motions for exiting element, including nested elements, complete  |
+ *          +----------------------------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                  +----------------------------------------------------------------+
+ *                  | 1. Remove `props.exitMotionClass`                              |
+ *                  | 2. Invoke `props.onStateChange` with `ExitSequenceEnd`         |
+ *                  +----------------------------------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                                  +--------------------------+
+ *                                  | Remove `props.exitClass` |
+ *                                  +--------------------------+
+ *                                                 |
+ *                                                 v
+ *                           +----------------------------------------+
+ *                           | 1. Remove exiting element from the DOM |
+ *                           | 2. Cancel `props.exitMotion`           |
+ *                           +----------------------------------------+
+ *                                                 |
+ *                                                 v
+ *                                         +--------------+
+ *                                         | End Sequence |
+ *                                         +--------------+
+ * ```
+ *
+ * # Inline Motion
+ *
+ * In addition to CSS initiated motions, inline motions can be defined for both the enter and exit
+ * sequences through {@link TransitionProps.enterMotion | `props.enterMotion`} and {@link
+ * TransitionProps.exitMotion | `props.exitMotion`}, respectively. These motions begin *after*
+ * the respective sequence and sequence start CSS classes are applied to the respective element.
+ *
+ * Inline motions must be defined in terms of a {@link TransitionMotion}, which contains the
+ * motion {@link MotionOptions | options} and {@link TransitionMotion.keyframes | keyframes}. The
+ * keyframes may be either an array of {@link MotionKeyframe | motion keyframes} or a function
+ * which returns an array of motion keyframes.
+ *
+ * When a function is specified, the function will be invoked for the enter and exit sequences of
+ * the respective transition. Each invocation will be with the transition {@link TransitionTarget |
+ * target}. This can be used to construct keyframes dynamically for each transition and
+ * sequence.
+ *
+ * An inline enter motion, which ends at the resting state of the entering element, stops affecting
+ * the element once it finishes, unless it specifies a fill. An inline exit motion, however, holds
+ * its end state until the exiting element is removed from the DOM, unless it specifies a fill of
+ * its own, since the exiting element has no resting state to return to; see {@link
+ * TransitionProps.exitMotion | `props.exitMotion`}.
+ *
+ * @param props - component properties
+ * @returns rendered element
+ * @throws {@link TypeError} `props.children` evaluated to a value which could not be mapped to
+ * {@link TransitionElement}
+ */
+export declare const Transition: FlowComponent<TransitionProps, TransitionProps["children"]>;

package/target/tsc/motion/velocity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Velocity estimator of a one-dimensional position.
+ *
+ * This estimates the velocity of a position, such as a pointer coordinate, from its newest
+ * {@link SAMPLE_CAPACITY | 20} samples. An estimate considers the newest sample, then each older
+ * sample in turn, as long as it is at most {@link SAMPLE_HORIZON_MSEC | 100ms} older than the
+ * newest sample *and* at most {@link MAX_SAMPLE_GAP_MSEC | 40ms} apart from the previous one. The
+ * velocity is the slope, at the newest sample, of lines and parabolas fitted by least squares to
+ * the newest of these samples.
+ *
+ * Consecutive samples which share a time stamp are reduced to one: the newest of them, as for
+ * coalesced pointer events, or the oldest, as for a clock which did not advance, whichever fits a
+ * parabola with the smaller residual variance.
+ *
+ * Of three kept samples or fewer, the velocity is the slope between the newest two; of four, it is
+ * the mean of that slope and the slope of the fitted parabola. Of more, it is the mean of the
+ * slopes of the lines and parabolas fitted to each window of the newest samples, weighted by their
+ * risk. The risk of a fit is the variance of its slope, given the noise of the positions, plus its
+ * squared bias, given its difference from the fits of higher degree. The noise is estimated from
+ * the residual of each sample from the parabola through its neighbors.
+ *
+ * Estimation does not allocate.
+ */
+export declare class VelocityTracker {
+    #private;
+    /**
+     * Construct a new tracker without samples.
+     */
+    constructor();
+    /**
+     * Add a sample.
+     *
+     * Once the tracker is full, this replaces the oldest retained sample. Samples are expected in
+     * chronological order, such as successive pointer events; this is **not** enforced.
+     *
+     * @param time - finite time, in milliseconds, such as `PointerEvent.timeStamp`
+     * @param position - finite position
+     * @throws {@link Error} `time` or `position` is not finite
+     */
+    addDataPoint(time: number, position: number): void;
+    /**
+     * Estimate velocity at newest sample.
+     *
+     * @param maximumVelocity - positive bound of the magnitude of the result, if any
+     * @returns velocity, in position units per second, or `0` without samples at two distinct
+     * contributing times or if the estimate is not finite
+     * @throws {@link Error} `maximumVelocity` is not positive
+     */
+    calculateVelocity(maximumVelocity?: number): number;
+    /**
+     * Remove all samples.
+     */
+    resetTracking(): void;
+}