@rive-app/canvas-single 2.40.0 → 2.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/canvas-single",
-  "version": "2.40.0",
+  "version": "2.41.0",
   "description": "Rive's high-level canvas based web api all in one js file.",
   "main": "rive.js",
   "homepage": "https://rive.app",

package/rive.d.ts

@@ -87,6 +87,12 @@ export declare class Layout {
     runtimeAlignment(rive: rc.RiveCanvas): rc.Alignment;
 }
 export { RuntimeLoader, type RuntimeCallback };
+/**
+ * @deprecated State machine inputs are deprecated and will be removed in a
+ * future major version: please use data binding properties instead. See
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+ * for how to migrate.
+ */
 export declare enum StateMachineInputType {
     Number = 56,
     Trigger = 58,
@@ -94,6 +100,10 @@ export declare enum StateMachineInputType {
 }
 /**
  * An input for a state machine
+ * @deprecated State machine inputs are deprecated and will be removed in a
+ * future major version: please use data binding properties instead. See
+ * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+ * for how to migrate.
  */
 export declare class StateMachineInput {
     readonly type: StateMachineInputType;
@@ -120,6 +130,11 @@ export declare class StateMachineInput {
      */
     delete(): void;
 }
+/**
+ * @deprecated Rive Events are deprecated and will be removed in a future major
+ * version: please use data binding instead. See
+ * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
+ */
 export declare enum RiveEventType {
     General = 128,
     OpenUrl = 131
@@ -150,13 +165,37 @@ export declare enum EventType {
     Play = "play",
     Pause = "pause",
     Stop = "stop",
+    /**
+     * @deprecated Loop events are deprecated and will be removed in a future
+     * major version: they are only reported for linear animation playback, which
+     * is deprecated. Use a state machine to control playback and data binding to
+     * react to changes instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide} for how
+     * to migrate.
+     */
     Loop = "loop",
     Draw = "draw",
     Advance = "advance",
+    /**
+     * @deprecated State change events are deprecated and will be removed in a
+     * future major version. Use data binding (view model property observers) or
+     * state machine actions to react to changes from your graphic instead. See
+     * {@link https://rive.app/docs/editor/state-machine/states#actions} for more details.
+     */
     StateChange = "statechange",
+    /**
+     * @deprecated Rive Events are deprecated and will be removed in a future
+     * major version: please use data binding instead. See
+     * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
+     */
     RiveEvent = "riveevent",
     AudioStatusChange = "audiostatuschange"
 }
+/**
+ * @deprecated Rive Events are deprecated and will be removed in a future major
+ * version: please use data binding instead. See
+ * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
+ */
 export type RiveEventPayload = rc.RiveEvent | rc.OpenUrlEvent;
 export interface Event {
     type: EventType;
@@ -164,6 +203,10 @@ export interface Event {
 }
 /**
  * Looping types: one-shot, loop, and ping-pong
+ * @deprecated Loop events are deprecated and will be removed in a future major
+ * version: they are only reported for linear animation playback, which is
+ * deprecated. Use a state machine to control playback and data binding to
+ * react to changes instead.
  */
 export declare enum LoopType {
     OneShot = "oneshot",// has value 0 in runtime
@@ -172,6 +215,10 @@ export declare enum LoopType {
 }
 /**
  * Loop events are returned through onloop callbacks
+ * @deprecated Loop events are deprecated and will be removed in a future major
+ * version: they are only reported for linear animation playback, which is
+ * deprecated. Use a state machine to control playback and data binding to
+ * react to changes instead.
  */
 export interface LoopEvent {
     animation: string;
@@ -224,11 +271,40 @@ declare class TaskQueueManager {
 }
 export interface RiveParameters {
     canvas: HTMLCanvasElement | OffscreenCanvas;
+    /**
+     * URI of the `.riv` file to load. Will be fetched by the runtime. Can be used instead of
+     * `buffer` or `riveFile`.
+     */
     src?: string;
+    /**
+     * ArrayBuffer of .riv file contents. Can be used instead of `src` or `riveFile` if you
+     * fetch the file contents yourself.
+     */
     buffer?: ArrayBuffer;
+    /**
+     * RiveFile instance if created separately. Useful if you reuse a Rive file across multiple instances.
+     * Can be used instead of `src` or `buffer`.
+     */
     riveFile?: RiveFile;
+    /**
+     * Name of the artboard to display.
+     */
     artboard?: string;
+    /**
+     * Name of the state machine to play.
+     */
+    stateMachine?: string;
+    /**
+     * @deprecated Use the `stateMachine` parameter to play a state machine
+     * instead. Support for starting playback with named animations will be
+     * removed in a future major version.
+     */
     animations?: string | string[];
+    /**
+     * @deprecated Use `stateMachine` with a single state machine name instead.
+     * Support for playing multiple state machines at once will be removed in a
+     * future major version.
+     */
     stateMachines?: string | string[];
     layout?: Layout;
     autoplay?: boolean;
@@ -281,6 +357,10 @@ export interface RiveParameters {
      * This flag is false by default to prevent any unwanted behaviors from taking place.
      * This means any special Rive Event will have to be handled manually by subscribing to
      * EventType.RiveEvent
+     *
+     * @deprecated Rive Events are deprecated and will be removed in a future
+     * major version: please use data binding instead. See
+     * {@link https://rive.app/docs/runtimes/web/rive-events} for how to migrate.
      */
     automaticallyHandleEvents?: boolean;
     /**
@@ -311,7 +391,22 @@ export interface RiveParameters {
     onPlay?: EventCallback;
     onPause?: EventCallback;
     onStop?: EventCallback;
+    /**
+     * @deprecated Loop events are deprecated and will be removed in a future
+     * major version: they are only reported for linear animation playback, which
+     * is deprecated. Use a state machine to control playback and data binding to
+     * react to changes instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide} for how
+     * to migrate.
+     */
     onLoop?: EventCallback;
+    /**
+     * @deprecated State change events are deprecated and will be removed in a
+     * future major version: use use data binding (view model property observers) or
+     * state machine actions to react to changes from your graphic instead. See
+     * {@link https://rive.app/docs/editor/state-machine/states#actions} for how
+     * to migrate.
+     */
     onStateChange?: EventCallback;
     onAdvance?: EventCallback;
     assetLoader?: AssetLoadCallback;
@@ -351,7 +446,21 @@ export interface RiveLoadParameters {
     autoplay?: boolean;
     autoBind?: boolean;
     artboard?: string;
+    /**
+     * Name of the state machine to play.
+     */
+    stateMachine?: string;
+    /**
+     * @deprecated Use the `stateMachine` parameter to play a state machine
+     * instead. Support for starting playback with named animations will be
+     * removed in a future major version.
+     */
     animations?: string | string[];
+    /**
+     * @deprecated Use `stateMachine` with a single state machine name instead.
+     * Support for playing multiple state machines at once will be removed in a
+     * future major version.
+     */
     stateMachines?: string | string[];
     useOffscreenRenderer?: boolean;
     shouldDisableRiveListeners?: boolean;
@@ -361,7 +470,21 @@ export interface RiveLoadParameters {
 }
 export interface RiveResetParameters {
     artboard?: string;
+    /**
+     * Name of the state machine to play.
+     */
+    stateMachine?: string;
+    /**
+     * @deprecated Use the `stateMachine` parameter to play a state machine
+     * instead. Support for starting playback with named animations will be
+     * removed in a future major version.
+     */
     animations?: string | string[];
+    /**
+     * @deprecated Use `stateMachine` with a single state machine name instead.
+     * Support for playing multiple state machines at once will be removed in a
+     * future major version.
+     */
     stateMachines?: string | string[];
     autoplay?: boolean;
     autoBind?: boolean;
@@ -624,6 +747,9 @@ export declare class Rive {
      * Returns a string from a given text run node name, or undefined if the text run
      * cannot be queried.
      *
+     * @deprecated Text run APIs are deprecated: use data binding instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
+     * for how to migrate.
      * @param textRunName - Name of the text run node associated with a text object
      * @returns - String value of the text run node or undefined
      */
@@ -631,19 +757,61 @@ export declare class Rive {
     /**
      * Sets a text value for a given text run node name if possible
      *
+     * @deprecated Text run APIs are deprecated: use data binding instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
+     * for how to migrate.
      * @param textRunName - Name of the text run node associated with a text object
      * @param textRunValue - String value to set on the text run node
      */
     setTextRunValue(textRunName: string, textRunValue: string): void;
+    /**
+     * Warns when playback-control names match linear animations in the
+     * Animator's instanced context; state machine playback remain supported.
+     *
+     * Remove for v3 release
+     */
+    private warnIfLinearAnimationNames;
+    /**
+     * Plays specified animations or state machines; if none specified, it
+     * unpauses everything.
+     * @param animationNames Animation or state machine name(s) to play.
+     *
+     * Deprecated usage: passing linear animation names (control playback with a
+     * state machine instead) and passing an array of names (this parameter
+     * becomes a single string in the next major version).
+     */
     play(animationNames?: string | string[], autoplay?: true): void;
+    /**
+     * Pauses specified animations or state machines; if none specified, pauses
+     * all.
+     * @param animationNames Animation or state machine name(s) to pause.
+     *
+     * Deprecated usage: passing linear animation names (control playback with a
+     * state machine instead) and passing an array of names (this parameter
+     * becomes a single string in the next major version).
+     */
     pause(animationNames?: string | string[]): void;
+    /**
+     * Scrubs specified animations to the given time; if none specified, scrubs
+     * all of them.
+     * @deprecated `scrub()` will be removed in a future major version: use a
+     * state machine to control playback instead
+     */
     scrub(animationNames?: string | string[], value?: number): void;
+    /**
+     * Stops specified animations or state machines; if none specified, stops
+     * them all.
+     * @param animationNames Animation or state machine name(s) to stop.
+     *
+     * Deprecated usage: passing linear animation names (control playback with a
+     * state machine instead) and passing an array of names (this parameter
+     * becomes a single string in the next major version).
+     */
     stop(animationNames?: string | string[] | undefined): void;
     /**
      * Resets the animation
      * @param artboard the name of the artboard, or default if none given
-     * @param animations the names of animations for playback
-     * @param stateMachines the names of state machines for playback
+     * @param stateMachine the name of the state machine for playback
      * @param autoplay whether to autoplay when reset, defaults to false
      *
      */
@@ -697,14 +865,24 @@ export declare class Rive {
     get stateMachineNames(): string[];
     /**
      * Returns the inputs for the specified instanced state machine, or an empty
-     * list if the name is invalid or the state machine is not instanced
+     * list if the name is invalid or the state machine is not instanced. Returns
+     * undefined if the file is not loaded yet.
+     *
+     * @deprecated State machine inputs are deprecated: use data binding
+     * properties instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+     * for how to migrate.
      * @param name the state machine name
-     * @returns the inputs for the named state machine
+     * @returns the inputs for the named state machine or undefined
      */
-    stateMachineInputs(name: string): StateMachineInput[];
+    stateMachineInputs(name: string): StateMachineInput[] | undefined;
     private retrieveInputAtPath;
     /**
      * Set the boolean input with the provided name at the given path with value
+     * @deprecated State machine inputs are deprecated: use data binding
+     * properties instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+     * for how to migrate.
      * @param input the state machine input name
      * @param value the value to set the input to
      * @param path the path the input is located at an artboard level
@@ -712,6 +890,10 @@ export declare class Rive {
     setBooleanStateAtPath(inputName: string, value: boolean, path: string): void;
     /**
      * Set the number input with the provided name at the given path with value
+     * @deprecated State machine inputs are deprecated: use data binding
+     * properties instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+     * for how to migrate.
      * @param input the state machine input name
      * @param value the value to set the input to
      * @param path the path the input is located at an artboard level
@@ -719,6 +901,10 @@ export declare class Rive {
     setNumberStateAtPath(inputName: string, value: number, path: string): void;
     /**
      * Fire the trigger with the provided name at the given path
+     * @deprecated State machine inputs are deprecated: use data binding
+     * properties instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#state-machine-inputs}
+     * for how to migrate.
      * @param input the state machine input name
      * @param path the path the input is located at an artboard level
      */
@@ -740,6 +926,10 @@ export declare class Rive {
      *
      * @remarks
      * If the text run cannot be found at the specified path, a warning will be logged to the console.
+     *
+     * @deprecated Text run APIs are deprecated: use data binding instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
+     * for how to migrate.
      */
     getTextRunValueAtPath(textName: string, path: string): string | undefined;
     /**
@@ -759,6 +949,10 @@ export declare class Rive {
      *
      * @remarks
      * If the text run cannot be found at the specified path, a warning will be logged to the console.
+     *
+     * @deprecated Text run APIs are deprecated: use data binding instead. See
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide#updating-text-runs-at-runtime}
+     * for how to migrate.
      */
     setTextRunValueAtPath(textName: string, value: string, path: string): void;
     get playingStateMachineNames(): string[];
@@ -788,6 +982,13 @@ export declare class Rive {
     get bounds(): Bounds;
     /**
      * Subscribe to Rive-generated events
+     *
+     * Note: subscribing to {@link EventType.RiveEvent},
+     * {@link EventType.StateChange}, or {@link EventType.Loop} is deprecated;
+     * use data binding instead. See
+     * {@link https://rive.app/docs/runtimes/web/rive-events} (Rive Events) and
+     * {@link https://rive.app/docs/editor/data-binding/migration-guide} for how
+     * to migrate Rive graphics to a data binding workflow instead.
      * @param type the type of event to subscribe to
      * @param callback callback to fire when the event occurs
      */