@rive-app/canvas-lite 2.37.7 → 2.38.0

package/rive_advanced.mjs.d.ts

@@ -755,6 +755,18 @@ export interface RiveEventCustomProperties {
   [key: string]: number | boolean | string;
 }
 
+/**
+ * Snapshot of the focus state returned by StateMachineInstance.focusState().
+ * Poll this each frame after advanceAndApply() to detect focus changes and
+ * determine whether a virtual keyboard should be shown or hidden.
+ */
+export interface FocusState {
+  /** True if any element currently holds focus in this state machine's active focus manager. */
+  hasFocus: boolean;
+  /** True if the focused element accepts keyboard input (e.g. a TextInput node). */
+  expectsKeyboardInput: boolean;
+}
+
 export declare class LinearAnimation {
   /**
    * The animation's loop type
@@ -877,6 +889,35 @@ export declare class StateMachineInstance {
    */
   pointerExit(x: number, y: number, id: number): void;
 
+  /**
+   * Returns true if this state machine has any focus nodes registered in its focus tree.
+   * Since the focus tree is unified across nested artboards, this covers the full scene.
+   * Use this to gate whether tab/focus traversal DOM listeners should be attached.
+   */
+  hasFocusNodes(): boolean;
+
+  /**
+   * Move focus to the next focusable node in the focus tree via the state machine's focus manager.
+   */
+  focusNext(): boolean;
+
+  /**
+   * Move focus to the previous focusable node in the focus tree via the state machine's focus manager.
+   */
+  focusPrevious(): boolean;
+
+  /**
+   * Clear focus from the Rive focus tree.
+   */
+  clearFocus(): void;
+
+  /**
+   * Returns metadata about current focus state:
+   *   1. Whether any node in the focus tree is currently focused
+   *   2. Whether the currently focused node expects keyboard input (i.e. keyboard/text input listener)
+   */
+  focusState(): FocusState;
+
   /**
    * Deletes the underlying instance created via the WASM. It's important to clean up this instance
    * when no longer in use

package/utils/finalizationRegistry.d.ts

@@ -35,7 +35,7 @@ declare class CustomFileAssetLoaderWrapper {
     assetLoader: rc.CustomFileAssetLoader;
     _assetLoaderCallback: AssetLoadCallbackWrapper;
     constructor(runtime: rc.RiveCanvas, loaderCallback: AssetLoadCallbackWrapper);
-    loadContents(asset: rc.FileAsset, bytes: any): Boolean;
+    loadContents(asset: rc.FileAsset, bytes: any): false | Boolean;
 }
 /**
  * Rive class representing a FileAsset with relevant metadata fields to describe

package/utils/index.d.ts

@@ -1,4 +1,6 @@
 export { registerTouchInteractions } from "./registerTouchInteractions";
+export { KeyboardInteractions, FocusSessionState } from "./registerKeyboardInteractions";
+export type { KeyboardInteractionsParams } from "./registerKeyboardInteractions";
 export { BLANK_URL, sanitizeUrl } from "./sanitizeUrl";
 export { Finalizable, ImageWrapper, AudioWrapper, FontWrapper, FileAssetWrapper, ImageAssetWrapper, AudioAssetWrapper, FontAssetWrapper, finalizationRegistry, CustomFileAssetLoaderWrapper, AssetLoadCallbackWrapper, FileFinalizer, createFinalization, } from "./finalizationRegistry";
 export { RiveFont } from "./riveFont";

package/utils/registerKeyboardInteractions.d.ts

@@ -0,0 +1,82 @@
+import * as rc from "../rive_advanced.mjs";
+export interface KeyboardInteractionsParams {
+    canvas: HTMLCanvasElement;
+    stateMachine: rc.StateMachineInstance;
+    /**
+     * Whether this canvas has focus nodes that should participate in tab traversal.
+     * When true, Tab/Shift+Tab will be intercepted and routed to the Rive focus manager.
+     * focusNext() returning false means no more traversable nodes — tab is released to the page.
+     */
+    hasFocusNodes: boolean;
+}
+/**
+ * Tracks the relationship between the canvas's DOM focus and Rive's internal focus for the
+ * current focus session.
+ *
+ * NotFocused   — the canvas is not the active DOM element, or Rive entered and then released focus
+ *                internally this session. Either way the next Tab should move on to the next page
+ *                element, so Tab events are ignored.
+ * EntryPending — the canvas has DOM focus but Rive holds no active focus node yet, and the next Tab should enter
+ *                the focus tree. This is the resting state for pointer-driven focus (a click on the
+ *                canvas), or an edge case for keyboard focus where initial focus action did not land on a focus node.
+ * RiveFocused  — a Rive node currently holds focus. Tab/Shift+Tab are routed to the Rive focus
+ *                manager and trapped inside the canvas until Rive notifies focus has ended.
+ *
+ * When keyboard focus lands on the canvas, onCanvasFocus reads the direction focus came from and
+ * moves into the focus tree immediately, going straight to RiveFocused. EntryPending is only set via pointer focus (or keyboard focus
+ * where focusNext()/focusPrevious() return false but respects tabindex).
+ */
+export declare enum FocusSessionState {
+    NotFocused = "notFocused",
+    EntryPending = "entryPending",
+    RiveFocused = "riveFocused"
+}
+/**
+ * Manages keyboard and DOM focus interactions for a Rive canvas.
+ *
+ * Tracks the canvas focus session state (focusSessionState) and routes
+ * Tab/Shift+Tab to the Rive state machine's focus manager. Exposes shared
+ * state as properties so the Rive render loop can read them directly.
+ */
+export declare class KeyboardInteractions {
+    focusSessionState: FocusSessionState;
+    private canvas;
+    private mainSm;
+    private hasFocusNodes;
+    constructor({ canvas, stateMachine, hasFocusNodes }: KeyboardInteractionsParams);
+    /**
+     * Set the FocusSessionState. Useful for invoking a Rive "blur" without actually blurring from the <canvas>. This
+     * helps put the DOM focus state on the canvas rather than the <body>, so the user doesn't lose the spot in page navigation
+     *
+     * @param state FocusSessionState enum
+     */
+    setFocusSessionState(state: FocusSessionState): void;
+    /**
+     * Called by pollFocusState on the Rive instance when it observes hasFocus=true. Rive acquired
+     * focus internally (e.g. via a listener action or state transition) without a DOM focus event,
+     * so mark the session RiveFocused.
+     */
+    notifyRiveFocused(): void;
+    /**
+     * Handles the canvas gaining browser focus. The behavior differs based on how focus was gained -
+     *
+     * Pointer-driven focus: the canvas now has focus but Rive holds nothing yet, so we move to EntryPending — this lets the
+     * next Tab enter the focus tree even when the focus is pointer-driven
+     *
+     * Keyboard-driven focus: we enter the Rive focus tree immediately once canvas gains focus.
+     * The direction is inferred from where focus came from: an element before the canvas in DOM order
+     * means a forward Tab (focusNext), one after means a Shift+Tab (focusPrevious). :focus-visible
+     * gates this so a click doesn't yank Rive focus to the first node on the focus event itself.
+     */
+    onCanvasFocus: (event: FocusEvent) => void;
+    onCanvasBlur: (_event: FocusEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+    /**
+     * Whether the canvas currently matches :focus-visible — the browser's heuristic for keyboard-
+     * (vs pointer-) driven focus. For older browser versions that don't support this selector, return false
+     * so that we don't incorrectly assume pointer vs keyboard focus. Next tab would enter the focus tree in those edge cases.
+     */
+    private isKeyboardDrivenFocus;
+    private cameFromBeforeCanvas;
+    cleanup(): void;
+}

package/utils/registerTouchInteractions.d.ts

@@ -11,9 +11,10 @@ export interface TouchInteractionsParams {
     dispatchPointerExit?: boolean;
     enableMultiTouch?: boolean;
     layoutScaleFactor?: number;
+    advanceAndDrain: (elapsedTime: number) => void;
 }
 /**
  * Registers mouse move/up/down callback handlers on the canvas to send meaningful coordinates to
  * the state machine pointer move/up/down functions based on cursor interaction
  */
-export declare const registerTouchInteractions: ({ canvas, artboard, stateMachines, renderer, rive, fit, alignment, isTouchScrollEnabled, dispatchPointerExit, enableMultiTouch, layoutScaleFactor, }: TouchInteractionsParams) => () => void;
+export declare const registerTouchInteractions: ({ canvas, artboard, stateMachines, renderer, rive, fit, alignment, isTouchScrollEnabled, dispatchPointerExit, enableMultiTouch, layoutScaleFactor, advanceAndDrain, }: TouchInteractionsParams) => () => void;