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

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

@@ -0,0 +1,34 @@
+/**
+ * Animation and transition definitions.
+ *
+ * This package provides the {@link applyMotion} function and {@link Transition} component for
+ * directly applying arbitrary motions to an element and applying motions to elements upon render
+ * change. These APIs use Web Animations. {@link createMaterialTransition} supplies motion pairs
+ * for the Material transition patterns through the same transition lifecycle.
+ *
+ * Components animate discrete state changes with CSS transitions whose easing and duration come
+ * from the `cw-Motion` spring roles, sampled from the Material springs at build time. {@link
+ * applySpringMotion} animates a numeric CSS property with a runtime spring instead, for motion a
+ * gesture drives or user input retargets mid-flight: it reads its stiffness and damping ratio from
+ * the same roles, preserves its velocity when retargeted, and accepts the release velocity
+ * estimated by a {@link VelocityTracker}. Runtime springs of a window share one animation-frame
+ * callback, available to other per-frame motion through {@link subscribeMotionFrames}.
+ *
+ * Web Animation motion completes without animating during server rendering or when the API is
+ * unavailable. Runtime springs settle immediately during server rendering, without an animation
+ * frame clock, or when reduced motion is requested. Both motion APIs honor reduced motion unless
+ * explicitly configured otherwise. {@link SUPPORTS_MOTION} describes Web Animations support only.
+ *
+ * @packageDocumentation
+ */
+export type { MotionFrameListener } from "./frame";
+export type { MaterialTransition, MaterialTransitionOptions, MaterialTransitionPattern } from "./material";
+export type { Motion, MotionDuration, MotionEasing, MotionKeyframe, MotionOptions } from "./motion";
+export type { SpringMotion, SpringOptions, SpringRole, SpringScheme, SpringSpeed } from "./spring";
+export type { TransitionElement, TransitionMotion, TransitionProps, TransitionState, TransitionTarget } from "./transition";
+export { subscribeMotionFrames } from "./frame";
+export { createMaterialTransition } from "./material";
+export { SUPPORTS_MOTION, applyMotion } from "./motion";
+export { applySpringMotion } from "./spring";
+export { EnterSequenceBegin, EnterSequenceEnd, ExitSequenceBegin, ExitSequenceEnd, Transition, TransitionBegin, TransitionEnd } from "./transition";
+export { VelocityTracker } from "./velocity";

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

@@ -0,0 +1,110 @@
+import type { MotionDuration } from "./motion";
+import type { TransitionMotion } from "./transition";
+/**
+ * Material transition pattern.
+ *
+ * | Pattern              | Relationship between the outgoing and incoming elements             |
+ * | -------------------- | ------------------------------------------------------------------- |
+ * | `containerTransform` | Incoming element expands from, or returns to, the outgoing one.     |
+ * | `fade`               | Elements enter or exit within the bounds of the screen.             |
+ * | `fadeThrough`        | Elements have no strong relationship, such as top-level destinations. |
+ * | `sharedAxis`         | Elements have a spatial or navigational relationship.               |
+ *
+ * @see {@link createMaterialTransition}
+ */
+export type MaterialTransitionPattern = "containerTransform" | "fade" | "fadeThrough" | "sharedAxis";
+/**
+ * Options of a {@link createMaterialTransition | Material transition}.
+ */
+export interface MaterialTransitionOptions {
+    /**
+     * Axis of a shared-axis transition.
+     *
+     * | Axis | Motion                                                      |
+     * | ---- | ----------------------------------------------------------- |
+     * | `x`  | Horizontal slide, mirrored for right-to-left text direction. |
+     * | `y`  | Vertical slide.                                             |
+     * | `z`  | Scale.                                                      |
+     *
+     * @defaultValue `"x"`
+     */
+    axis?: "x" | "y" | "z";
+    /**
+     * Navigation direction.
+     *
+     * Forward shared-axis transitions move towards the inline end, the bottom, or the viewer, and
+     * backward transitions in the opposite direction. A forward container transform enters the
+     * incoming element, and a backward container transform returns to it.
+     *
+     * @defaultValue `true`
+     */
+    forward?: boolean;
+    /**
+     * Slide distance of `x` and `y` shared-axis transitions, in CSS pixels.
+     *
+     * @defaultValue `30`
+     */
+    distance?: number;
+    /**
+     * Duration overriding the duration roles of the pattern.
+     */
+    duration?: MotionDuration;
+}
+/**
+ * Inline motions which can be spread onto {@link ./transition#Transition} properties.
+ */
+export interface MaterialTransition {
+    /**
+     * Motion applied to the incoming transition element.
+     *
+     * @see {@link ./transition#TransitionProps.enterMotion}
+     */
+    readonly enterMotion: Readonly<TransitionMotion>;
+    /**
+     * Motion applied to the outgoing transition element.
+     *
+     * @see {@link ./transition#TransitionProps.exitMotion}
+     */
+    readonly exitMotion: Readonly<TransitionMotion>;
+}
+/**
+ * Create the motions of a Material transition pattern.
+ *
+ * The returned motions are spread onto a {@link ./transition#Transition}, which runs them in its
+ * default parallel order:
+ *
+ * ```tsx
+ * <Transition {...createMaterialTransition("sharedAxis", { forward: forward() })}>
+ *     {page}
+ * </Transition>
+ * ```
+ *
+ * | Pattern              | Motion                                                                |
+ * | -------------------- | --------------------------------------------------------------------- |
+ * | `containerTransform` | Containers morph between their bounds and shapes over a scrim.        |
+ * | `fade`               | Incoming element fades in by 30% progress while scaling up from 80%.  |
+ * | `fadeThrough`        | Outgoing element fades out by 35%, then incoming fades in from 92%.   |
+ * | `sharedAxis`         | Fade through while sliding 30px along `x`/`y`, or scaling along `z`.  |
+ *
+ * These are web adaptations of MDC-Android's `MaterialContainerTransform`, `MaterialFade`,
+ * `MaterialFadeThrough`, and `MaterialSharedAxis`, with their default thresholds, scales, and
+ * distances, and the themed `cw-Motion` duration and easing roles they use: fade enters over
+ * `medium-4` with emphasized decelerate easing and exits over `short-3` with emphasized accelerate
+ * easing; fade through and shared axis last `long-1`, and a container transform `long-2` when
+ * entering and `medium-4` when returning, all with emphasized easing. Reduced motion is honored
+ * through {@link ./motion#applyMotion}.
+ *
+ * A container transform measures both elements when it begins, so both must be laid out at their
+ * resting bounds at the same time, typically positioned in a shared stacking context. Each element
+ * is scaled, rather than resized, into the transforming container and clipped to its shape, so its
+ * content does not reflow and its own shadow is clipped while it transforms. The containers should
+ * be opaque; the incoming one appears above the outgoing one. The scrim is an element inserted
+ * immediately before the outgoing element for the duration of the transition.
+ *
+ * @param pattern - relationship between the outgoing and incoming elements
+ * @param opts - axis, navigation direction, distance, and duration
+ * @returns motions for a {@link ./transition#Transition}
+ * @throws {@link Error} `pattern` or `opts` are invalid
+ * @see MDC-Android `lib/java/com/google/android/material/transition/`
+ */
+export declare function createMaterialTransition(pattern: MaterialTransitionPattern, opts?: Readonly<MaterialTransitionOptions>): MaterialTransition;

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

@@ -0,0 +1,235 @@
+/**
+ * {@link Motion} easing function.
+ *
+ * Easing functions can be either literal easing functions, CSS variable name, or, the
+ * `animation-timing-function` or `transition-timing-function` CSS properties. Non-literal values
+ * are resolved from the style of the target element the motion is applied to. When resolving from
+ * CSS property values, if the CSS property is assigned to multiple easing functions, the last
+ * easing function is used.
+ *
+ * @see {@link MotionOptions.easing}
+ */
+export type MotionEasing = string | `--${string}` | `${"animation" | "transition"}-timing-function`;
+/**
+ * {@link Motion} duration.
+ *
+ * Durations can be either a `number` of milliseconds, CSS variable name, or, the
+ * `animation-duration` or `transition-duration` CSS properties. Like {@link MotionEasing},
+ * non-literal values are resolved from the style of the target element the motion is applied to.
+ * See {@link MotionEasing} for more information.
+ *
+ * @see {@link MotionOptions.duration}
+ * @see {@link MotionOptions.endDelay}
+ * @see {@link MotionOptions.startDelay}
+ */
+export type MotionDuration = number | `--${string}` | `${"animation" | "transition"}-duration`;
+/**
+ * {@link Motion} keyframe.
+ *
+ * A keyframe may be a literal string constant or an object. Literal string constants evaluate to
+ * one or more keyframes representing the specific predefined motion type. Object values are
+ * expected to be `Keyframe` objects, whose `easing` key may be mapped to an {@link MotionEasing}
+ * value.
+ *
+ * | Predefined Motion   | Description                                                            |
+ * | ------------------- | ---------------------------------------------------------------------- |
+ * | `clip-in-block`     | Clip element in, along block axis, using `clip-path`.                  |
+ * | `clip-in-inline`    | Clip element in, along inline axis, using `clip-path`.                 |
+ * | `clip-out-block`    | Clip element out, along block axis, using `clip-path`.                 |
+ * | `clip-out-inline`   | Clip element out, along inline axis, using `clip-path`.                |
+ * | `expand-in-block`   | Expand element, along block axis, from `0` to resting size.            |
+ * | `expand-in-inline`  | Expand element, along inline axis from `0` to resting size.            |
+ * | `expand-out-block`  | Shrink element, along block axis, from current size to `0`.            |
+ * | `expand-out-inline` | Shrink element, along inline axis, from current size to `0`.           |
+ * | `fade-in`           | Transition `opacity` from `0` to resting value.                        |
+ * | `fade-out`          | Transition `opacity` from current value to `0`.                        |
+ * | `slide-in-block`    | Slide element in, along block axis, using `translate` and `clip-path`. |
+ * | `slide-in-inline`   | Slide element in, along inline axis, using `translate` and `clip-path`. |
+ * | `slide-out-block`   | Slide element out, along block axis, using `translate` and `clip-path`. |
+ * | `slide-out-inline`  | Slide element out, along inline axis, using `translate` and `clip-path`. |
+ * | `zoom-in`           | Transition `scale` from `0` to resting value.                          |
+ * | `zoom-out`          | Transition `scale` from current value to `0`.                          |
+ *
+ * Predefined motions which rely on current or resting style property values, the property values
+ * are resolved from the *current* value of the property, when motion is first constructed, to the
+ * value of the property *after* motion playback begins.
+ */
+export type MotionKeyframe = (Omit<Keyframe, "easing"> & {
+    easing?: MotionEasing | undefined;
+}) | `clip-${"in" | "out"}-${"block" | "inline"}` | `expand-${"in" | "out"}-${"block" | "inline"}` | `fade-${"in" | "out"}` | `slide-${"in" | "out"}-${"block" | "inline"}` | `zoom-${"in" | "out"}`;
+/**
+ * Options controlling how a motion is {@link applyMotion | applied} to a target element.
+ */
+export interface MotionOptions {
+    /**
+     * Honor the target document's reduced-motion preference.
+     *
+     * @defaultValue `true`
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Cache to use for persisting CSS styles.
+     *
+     * This cache, when specified, is populated with CSS properties and variables which are
+     * accessed when resolving easing functions, durations, etc. If CSS properties and
+     * variables may change between subsequent invocations of {@link applyMotion}, for the
+     * same target element and keyframes, then this should *not* be specified.
+     */
+    cache?: Record<string, unknown>;
+    /**
+     * CSS selector of pseudo-element to apply motion to.
+     *
+     * When omitted or `undefined`, the motion is applied to the target element; otherwise,
+     * the motion is applied to the specified pseudo-element of the target element.
+     * Additionally, any option assigned to a CSS property name or variable name will be
+     * resolved from the styling of the pseudo element.
+     */
+    pseudoElement?: string;
+    /**
+     * Direction in which the motion is applied.
+     *
+     * | Direction           | Description                                                 |
+     * | ------------------- | ----------------------------------------------------------- |
+     * | `alternate`         | Alternate between `normal` and `reverse` at each iteration. |
+     * | `alternate-reverse` | Alternate between `reverse` and `normal` at each iteration. |
+     * | `normal`            | Interpolate from start values to end values.                |
+     * | `reverse`           | Interpolate from end values to start values.                |
+     *
+     * @defaultValue `"normal"`
+     */
+    direction?: "alternate" | "alternate-reverse" | "normal" | "reverse";
+    /**
+     * Persist motion effects to element.
+     *
+     * | Fill        | Description                              |
+     * | ----------- | ---------------------------------------- |
+     * | `backwards` | Persist prior to starting motion.        |
+     * | `both`      | Implies both `backwards` and `forwards`. |
+     * | `forwards`  | Persist after motion end.                |
+     * | `none`      | Do not persist.                          |
+     *
+     * @defaultValue `"none"`
+     */
+    fill?: "backwards" | "both" | "forwards" | "none";
+    /**
+     * Value composition between motion and other motions applied in parallel.
+     *
+     * | Composite    | Description                                                           |
+     * | ------------ | --------------------------------------------------------------------- |
+     * | `accumulate` | Effective value is sum of value defined by this motion and other motions. |
+     * | `add`        | Effective value is additive.                                          |
+     * | `replace`    | Value of other motion is replaced with value defined by this motion.  |
+     *
+     * @defaultValue `"replace"`
+     */
+    composite?: "accumulate" | "add" | "replace";
+    /**
+     * Number of iterations.
+     *
+     * @defaultValue `1`
+     */
+    iterations?: number;
+    /**
+     * Easing function.
+     *
+     * @defaultValue `"linear"`
+     */
+    easing?: MotionEasing;
+    /**
+     * Duration of motion.
+     */
+    duration?: MotionDuration;
+    /**
+     * Start delay of motion.
+     */
+    startDelay?: MotionDuration;
+    /**
+     * End delay of motion.
+     */
+    endDelay?: MotionDuration;
+}
+/**
+ * Controller of an {@link applyMotion | applied} motion.
+ */
+export interface Motion {
+    /**
+     * Promise which resolves once motion has finished playing.
+     *
+     * This property is updated with a new promise each time a motion exits the `finished`
+     * play {@link Motion.playState | state}.
+     */
+    readonly finished: Promise<Motion>;
+    /**
+     * Promise which resolves once motion can begin playback.
+     *
+     * This property is updated with a new promise each time a motion enters into the `pending`
+     * play {@link Motion.playState | state}.
+     */
+    readonly ready: Promise<Motion>;
+    /**
+     * Motion is pending an asynchronous operation.
+     */
+    readonly pending: boolean;
+    /**
+     * Playback state of motion.
+     *
+     * This is set to `"idle"`, `"running"`, `"paused"`, or `"finished"` based on whether
+     * motion timeline has not yet been resolved, motion is running, motion was suspended, or
+     * motion has reached end of its timeline, respectively.
+     */
+    readonly playState: "finished" | "idle" | "paused" | "running";
+    /**
+     * Update motion playback rate after synchronizing playback position.
+     *
+     * @param rate - value greater than, less than, or equal to zero to speed up or reverse,
+     * play backwards, or pause motion
+     */
+    updatePlaybackRate(rate: number): void;
+    /**
+     * Clear all pending keyframes and abort playback.
+     *
+     * Upon return, if play {@link Motion.playState | state} was not `"idle"`, then the {@link
+     * Motion.finished | finished} promise, prior to when this method was invoked, is rejected
+     * with a `DOMException`.
+     */
+    cancel(): void;
+}
+/**
+ * Motion is supported by user-agent.
+ *
+ * This is `true` if, and only if:
+ *
+ * 1. Executing environment is not {@link solid-js/web#isServer | server}.
+ *
+ * 2. User-agent supports Web Animations API required by motion functions and components.
+ */
+export declare const SUPPORTS_MOTION: boolean;
+/**
+ * Apply motion to an element or pseudo-element.
+ *
+ * If {@link MotionOptions.pseudoElement | `opts.pseudoElement`} is specified, then the motion is
+ * applied to the specified pseudo-element of `elem`; otherwise, the motion is applied to `elem`.
+ * The motion applied is composed of keyframes defined in `frames`. The `frames` array may contain
+ * explicit keyframe objects or predefined motion name strings.
+ *
+ * Predefined motion strings evaluate to keyframe objects, computed for the target element,
+ * usually with a start and end keyframe. Predefined motions whose computed frames contain an end
+ * frame, the end frame will applied at an offset of `1`. Computed start frames, however, are
+ * applied in the order the predefined motion name appears within `frames`.
+ *
+ * If the user-agent does not {@link SUPPORTS_MOTION | support} motion, this returns a motion in
+ * a finished play {@link Motion.playState | state}.
+ *
+ * @param elem - target element
+ * @param frames - frames of motion to apply
+ * @param opts - options to apply motion with
+ * @returns resulting motion
+ * @throws {@link Error} `opts` are malformed
+ *
+ * @remarks
+ * A motion which honors reduced motion listens for preference changes until it finishes or is
+ * {@link Motion.cancel | cancelled}. Cancel a motion which never finishes, such as one with
+ * infinite {@link MotionOptions.iterations | iterations} or a zero playback rate, once it is no
+ * longer needed; otherwise, the listener retains the motion and its target.
+ */
+export declare function applyMotion(elem: Element, frames: readonly MotionKeyframe[], opts: Readonly<MotionOptions>): Motion;

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

@@ -0,0 +1,223 @@
+import type { StyleElement } from "../dom";
+/**
+ * Material spring scheme.
+ *
+ * | Scheme       | Spatial springs                                    | Effect springs    |
+ * | ------------ | -------------------------------------------------- | ----------------- |
+ * | `expressive` | Bounce; for prominent and hero interactions.       | Critically damped |
+ * | `standard`   | Barely overshoot; for utilitarian interactions.    | Critically damped |
+ *
+ * @see {@link SpringOptions.scheme}
+ */
+export type SpringScheme = "expressive" | "standard";
+/**
+ * Category of the property a spring animates.
+ *
+ * Use `"spatial"` for position, size and shape, which may overshoot, and `"effect"` for color,
+ * opacity, and other values which must not overshoot.
+ *
+ * @see {@link SpringOptions.role}
+ */
+export type SpringRole = "effect" | "spatial";
+/**
+ * Relative speed of a spring within its scheme and role.
+ *
+ * Use `"fast"` for small component feedback, `"default"` for motion covering part of the screen,
+ * and `"slow"` for full-screen motion.
+ *
+ * @see {@link SpringOptions.speed}
+ */
+export type SpringSpeed = "default" | "fast" | "slow";
+/**
+ * Options of a {@link applySpringMotion | spring motion}.
+ *
+ * Springs have unit mass. Unless given, the stiffness and damping ratio are those of the Material
+ * spring selected by {@link SpringOptions.role | `role`} and {@link SpringOptions.speed | `speed`}.
+ */
+export interface SpringOptions {
+    /**
+     * Spring scheme whose presets supply an omitted stiffness or damping ratio.
+     *
+     * When omitted, the stiffness and damping ratio are read from the
+     * `--cw-Motion-spring-<role>-<speed>-stiffness` and `--cw-Motion-spring-<role>-<speed>-damping`
+     * roles of the element, which follow the nearest `cw-theme-standard` or `cw-theme-expressive`
+     * scope like every other motion role. The standard presets apply when these roles are
+     * unavailable, such as during server rendering, for an element outside its document, or
+     * without the motion stylesheet.
+     *
+     * @defaultValue scheme of the motion roles applied to the element
+     */
+    scheme?: SpringScheme;
+    /**
+     * Category of the animated property.
+     *
+     * @defaultValue `"spatial"`
+     */
+    role?: SpringRole;
+    /**
+     * Relative speed of the spring.
+     *
+     * @defaultValue `"default"`
+     */
+    speed?: SpringSpeed;
+    /**
+     * Positive, finite stiffness.
+     *
+     * Overrides the stiffness selected by {@link SpringOptions.scheme | `scheme`}, {@link
+     * SpringOptions.role | `role`}, and {@link SpringOptions.speed | `speed`}.
+     */
+    stiffness?: number;
+    /**
+     * Positive, finite damping ratio.
+     *
+     * Ratios below `1` overshoot, `1` is critically damped, and ratios above `1` are over-damped.
+     * Overrides the ratio selected by {@link SpringOptions.scheme | `scheme`}, {@link
+     * SpringOptions.role | `role`}, and {@link SpringOptions.speed | `speed`}.
+     */
+    damping?: number;
+    /**
+     * Finite initial velocity, in property units per second.
+     *
+     * Pass the release velocity of a gesture, for example from a {@link ./velocity#VelocityTracker
+     * | velocity tracker}, so the spring continues the gesture's momentum.
+     *
+     * @defaultValue `0`
+     */
+    velocity?: number;
+    /**
+     * Positive, finite settle threshold, in property units.
+     *
+     * The spring settles at its destination once its displacement is below this threshold *and*
+     * its speed is below {@link VELOCITY_THRESHOLD_MULTIPLIER | 62.5} thresholds per second, that
+     * is, once it would move less than the threshold within a 16ms frame. The default depends on
+     * {@link SpringOptions.unit | `unit`}:
+     *
+     * | Unit        | Threshold | Source                                                    |
+     * | ----------- | --------- | --------------------------------------------------------- |
+     * | `px`        | `0.4`     | Compose `Dp.VisibilityThreshold`                          |
+     * | `deg`       | `0.1`     | Android `MIN_VISIBLE_CHANGE_ROTATION_DEGREES`             |
+     * | `%`         | `0.1`     | `0.4px` of a `400px` reference box                        |
+     * | none, other | `0.002`   | Android `MIN_VISIBLE_CHANGE_SCALE`                        |
+     *
+     * The Android values are constants of `androidx.dynamicanimation.animation.DynamicAnimation`.
+     *
+     * @defaultValue threshold of {@link SpringOptions.unit | `unit`}, see above
+     */
+    threshold?: number;
+    /**
+     * CSS unit appended to the numeric value, such as `"px"`.
+     *
+     * Use an empty string for unitless properties, and for custom properties whose consumers
+     * supply the unit.
+     *
+     * @defaultValue `""`
+     */
+    unit?: string;
+    /**
+     * Settle immediately while the element's document prefers reduced motion.
+     *
+     * A change of preference to reduced motion also settles a running spring at its destination.
+     *
+     * @defaultValue `true`
+     */
+    respectReducedMotion?: boolean;
+}
+/**
+ * Controller of a {@link applySpringMotion | spring motion}.
+ *
+ * A spring changes its destination without discarding its velocity. Its sampled value remains
+ * applied as an inline style after it settles or is cancelled, so a caller can retarget it from its
+ * current position. Retargeting a settled or cancelled spring starts a new run, with a new {@link
+ * SpringMotion.finished | completion promise}.
+ */
+export interface SpringMotion {
+    /**
+     * Most recently sampled value, in property units.
+     *
+     * Reading this does not advance the spring, and does not establish a Solid dependency.
+     */
+    readonly value: number;
+    /**
+     * Most recently sampled velocity, in property units per second.
+     *
+     * Settling sets this to `0`; cancellation retains the sampled velocity.
+     */
+    readonly velocity: number;
+    /**
+     * Lifecycle state.
+     *
+     * | State      | Description                                   |
+     * | ---------- | --------------------------------------------- |
+     * | `finished` | Spring settled at its destination.            |
+     * | `idle`     | Spring was cancelled before it settled.       |
+     * | `running`  | Spring is moving towards its destination.     |
+     *
+     * This is not a Solid signal.
+     */
+    readonly playState: "finished" | "idle" | "running";
+    /**
+     * Completion promise of the current run.
+     *
+     * Resolves with this controller once the spring settles, and rejects with an `AbortError`
+     * `DOMException` once it is cancelled. Retargeting a running spring retains the promise;
+     * retargeting a settled or cancelled spring replaces it, so read this again after restarting.
+     */
+    readonly finished: Promise<SpringMotion>;
+    /**
+     * Change the destination, preserving the current value and velocity.
+     *
+     * A running spring is first sampled at the current time of its document. A settled or
+     * cancelled spring starts a new run from its retained value and velocity.
+     *
+     * @param value - finite destination, in property units
+     * @throws {@link Error} `value` is not finite
+     */
+    retarget(value: number): void;
+    /**
+     * Stop the current run, retaining its sampled value and velocity.
+     *
+     * Rejects {@link SpringMotion.finished | `finished`} with an `AbortError` `DOMException`. This
+     * has no effect on a settled or cancelled spring.
+     */
+    cancel(): void;
+}
+/**
+ * Animate a numeric CSS property with a Material spring.
+ *
+ * The spring moves the property of `elem` from `from` towards `to`, writing the sampled value,
+ * followed by {@link SpringOptions.unit | `opts.unit`}, as an inline style on every animation
+ * frame. Its stiffness and damping ratio come from the `cw-Motion` spring roles of `elem`, so the
+ * nearest `cw-theme-standard` or `cw-theme-expressive` scope selects its scheme (see {@link
+ * SpringOptions.scheme}). Use effect springs for opacity and other bounded values, and spatial
+ * springs for position, size or shape.
+ *
+ * Unlike CSS transitions, a spring is interruptible without a velocity discontinuity: {@link
+ * SpringMotion.retarget | retargeting} it continues from its current value and velocity, and
+ * {@link SpringOptions.velocity | `opts.velocity`} hands it the release velocity of a gesture.
+ * All springs of a window share one animation-frame callback and frame clock. A spring settles
+ * immediately during server rendering, without an animation-frame clock, or while reduced motion
+ * is preferred (unless {@link SpringOptions.respectReducedMotion | `respectReducedMotion`} is
+ * `false`). Its value remains applied after it settles.
+ *
+ * ```ts
+ * const spring = applySpringMotion(thumb, "translate", 0, 20, { speed: "fast", unit: "px" });
+ *
+ * // a later toggle reverses the motion without a velocity jump:
+ * spring.retarget(0);
+ * ```
+ *
+ * @param elem - element receiving the property
+ * @param property - CSS property name, including custom properties
+ * @param from - finite initial value
+ * @param to - finite destination
+ * @param opts - spring characteristics and CSS unit
+ * @returns interruptible spring controller
+ * @throws {@link Error} `from`, `to`, or `opts` are invalid
+ *
+ * @remarks
+ * The stiffness, damping ratio, and window are resolved when the spring is created; reading the
+ * motion roles costs one `getComputedStyle()` call. Moving the element to another scope or
+ * document does not reconfigure the spring. Within a Solid owner the spring is cancelled when the
+ * owner is disposed; otherwise, the caller must cancel a spring it no longer needs.
+ */
+export declare function applySpringMotion(elem: StyleElement, property: string, from: number, to: number, opts?: Readonly<SpringOptions>): SpringMotion;

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

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export {};