@rive-app/canvas-single 2.38.5 → 2.39.0

package/rive_advanced.mjs.d.ts

@@ -391,6 +391,12 @@ export declare class File {
    */
   enums(): DataEnum[];
 
+  /**
+   * Returns the names of the file's global view models, in file order.
+   * @returns array of global view model names
+   */
+  globalViewModelNames(): string[];
+
   unref(): void;
 
   /**
@@ -593,6 +599,27 @@ export declare class Artboard {
    * @param instance - Renderer context to draw with
    */
   bindViewModelInstance(instance: ViewModelInstance): void;
+  /**
+   * Sets the main view model instance without rebinding. Call bind() to apply.
+   */
+  setViewModelInstance(instance: ViewModelInstance): void;
+  /**
+   * Applies the current data context (rebinds data binds). No-op if nothing set.
+   */
+  bind(): void;
+  /**
+   * Sets/replaces the global view model instance bound under the given global
+   * view model name without rebinding, preserving the main instance and the
+   * other globals' order. Call bind() to apply.
+   * @returns false if the name does not match a global view model in the file.
+   */
+  setGlobalViewModelInstance(name: string, instance: ViewModelInstance): boolean;
+  /**
+   * @returns the global view model instance currently bound under the given
+   * name (the runtime-seeded default or a previously set instance), or null if
+   * the name does not match a global view model in the file.
+   */
+  globalViewModelInstance(name: string): ViewModelInstance | null;
 
   didChange(): boolean;
 }
@@ -940,6 +967,105 @@ export declare class StateMachineInstance {
    * @param instance - Renderer context to draw with
    */
   bindViewModelInstance(instance: ViewModelInstance): void;
+  /**
+   * Sets the main view model instance without rebinding. Call bind() to apply.
+   */
+  setViewModelInstance(instance: ViewModelInstance): void;
+  /**
+   * Applies the current data context (rebinds data binds). No-op if nothing set.
+   */
+  bind(): void;
+  /**
+   * Sets/replaces the global view model instance bound under the given global
+   * view model name without rebinding, preserving the main instance and the
+   * other globals' order. Call bind() to apply.
+   * @returns false if the name does not match a global view model in the file.
+   */
+  setGlobalViewModelInstance(name: string, instance: ViewModelInstance): boolean;
+  /**
+   * @returns the global view model instance currently bound under the given
+   * name (the runtime-seeded default or a previously set instance), or null if
+   * the name does not match a global view model in the file.
+   */
+  globalViewModelInstance(name: string): ViewModelInstance | null;
+
+  /**
+   * Enables semantic tree tracking for this state machine instance.
+   * Once enabled, the runtime builds and maintains a semantic tree that
+   * describes the accessible structure of the artboard (roles, labels,
+   * states, bounds). Call this before using drainSemanticsDiff().
+   */
+  enableSemantics(): void;
+
+  /**
+   * Returns the incremental semantic diff since the last call, or null if
+   * nothing changed. Each diff contains arrays of added/removed/moved nodes,
+   * updated semantic properties, updated geometry, and children reorderings.
+   */
+  drainSemanticsDiff(): SemanticsDiff | null;
+
+  /**
+   * Fire a semantic action on the node with the given ID.
+   * @param nodeId - The semantic node ID to target
+   * @param actionType - 0 = tap, 1 = increase, 2 = decrease
+   */
+  fireSemanticAction(nodeId: number, actionType: number): void;
+
+  /**
+   * Request focus on the semantic node with the given ID.
+   * Routes through SemanticManager to focus the FocusData sibling of the
+   * SemanticData that owns the node. Returns true if focus was set.
+   * @param nodeId - The semantic node ID to focus
+   * @returns boolean - True if focus was set, false otherwise
+   */
+  focusSemanticNode(nodeId: number): boolean;
+
+  /**
+   * Clears focus from the currently focused node in the focus tree.
+   */
+  clearFocus(): void;
+}
+
+export interface SemanticsDiffNode {
+  id: number;
+  role: number;
+  label: string;
+  value: string;
+  hint: string;
+  stateFlags: number;
+  traitFlags: number;
+  headingLevel: number;
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  parentId: number;
+  siblingIndex: number;
+}
+
+export interface SemanticsBoundsUpdate {
+  id: number;
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+export interface SemanticsChildrenUpdate {
+  parentId: number;
+  childIds: number[];
+}
+
+export interface SemanticsDiff {
+  frameNumber: number;
+  treeVersion: number;
+  rootId: number;
+  removed: number[];
+  added: SemanticsDiffNode[];
+  moved: SemanticsDiffNode[];
+  childrenUpdated: SemanticsChildrenUpdate[];
+  updatedSemantic: SemanticsDiffNode[];
+  updatedGeometry: SemanticsBoundsUpdate[];
 }
 
 export declare class SMIInput {
@@ -973,6 +1099,7 @@ export declare class SMIInput {
 export declare type ViewModelProperty = {
   name: string;
   type: DataType;
+  enumName?: string;
 };
 
 export declare class ViewModelInstanceValue {
@@ -1028,6 +1155,9 @@ export declare class ViewModelInstanceList extends ViewModelInstanceValue {
 export declare class ViewModelInstanceAssetImage extends ViewModelInstanceValue {
   value(image: ImageInternal | null): void;
 }
+export declare class ViewModelInstanceAssetFont extends ViewModelInstanceValue {
+  value(font: FontInternal | null): void;
+}
 export declare class ViewModelInstanceArtboard extends ViewModelInstanceValue {
   value(artboard: BindableArtboard | Artboard): void;
   viewModelInstance(viewModelInstance: ViewModelInstance): void;
@@ -1044,6 +1174,7 @@ export declare class ViewModelInstance {
   list(path: string): ViewModelInstanceList;
   viewModel(path: string): ViewModelInstance;
   image(path: string): ViewModelInstanceAssetImage;
+  font(path: string): ViewModelInstanceAssetFont;
   artboard(path: string): ViewModelInstanceArtboard;
   replaceViewModel(path: string, value: ViewModelInstance): boolean;
   incrementReferenceCount(): void;

package/utils/registerKeyboardInteractions.d.ts

@@ -8,6 +8,12 @@ export interface KeyboardInteractionsParams {
      * focusNext() returning false means no more traversable nodes — tab is released to the page.
      */
     hasFocusNodes: boolean;
+    /**
+     * Optional accessibility overlay that should be treated as part of this Rive
+     * instance's focus domain. This is lazy because the overlay may be created
+     * after keyboard listeners are registered.
+     */
+    getOverlayElement?: () => HTMLElement | null;
 }
 /**
  * Tracks the relationship between the canvas's DOM focus and Rive's internal focus for the
@@ -43,7 +49,17 @@ export declare class KeyboardInteractions {
     private canvas;
     private mainSm;
     private hasFocusNodes;
-    constructor({ canvas, stateMachine, hasFocusNodes }: KeyboardInteractionsParams);
+    /** Cached callback that returns the accessibility overlay element once created. */
+    private getOverlayElement?;
+    /** Whether the canvas currently has browser DOM focus. */
+    private canvasHasFocus;
+    /** After Tab exits the last Rive node, ignore keydowns until focus re-enters the focus domain. */
+    private focusDomainReleased;
+    /** Overlay element currently wired with focusin/keydown listeners, if any. */
+    private currentOverlayElement;
+    /** Canvas parent (or document) watched for focusin to attach overlay listeners lazily. */
+    private focusDomainHost;
+    constructor({ canvas, stateMachine, hasFocusNodes, getOverlayElement, }: 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
@@ -70,7 +86,21 @@ export declare class KeyboardInteractions {
      */
     onCanvasFocus: (event: FocusEvent) => void;
     onCanvasBlur: (_event: FocusEvent) => void;
+    private onOverlayFocusIn;
+    private onFocusDomainHostFocusIn;
     onKeyDown: (event: KeyboardEvent) => void;
+    /**
+     * Whether Rive should handle this keydown — i.e. it currently owns keyboard input.
+     * True when focus is anywhere in the Rive focus domain (the canvas itself or the
+     * accessibility overlay), OR a focus session is active and the key landed on the
+     * canvas.
+     */
+    private shouldRiveHandleKeyEvent;
+    /** Rive focus domain = the canvas itself OR the accessibility overlay. */
+    private isInFocusDomain;
+    /** Overlay only (excludes the canvas) — the accessibility overlay subtree. */
+    private isInOverlay;
+    private syncOverlayListener;
     /**
      * 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