@rive-app/canvas-single 2.39.0 → 2.39.1

package/semantics/accessibilityOverlay.d.ts

@@ -0,0 +1,217 @@
+import type * as rc from "../rive_advanced.mjs";
+import type { SemanticTreeModel } from "./semanticTreeModel";
+import { SemanticActionType, RiveSemanticsOptions } from "./types";
+export interface AccessibilityOverlayOptions {
+    canvas: HTMLCanvasElement;
+    /** Unique string per Rive instance (used for prefixed IDs). */
+    instanceId: string;
+    /** Optional options for controlling semantic tree behavior and rendering */
+    semanticsOptions: RiveSemanticsOptions;
+    /** Callback to fire a semantic action back into the state machine. */
+    fireAction: (nodeId: number, actionType: SemanticActionType) => void;
+    /** Callback when AT focuses a semantic node (routes to SemanticManager::requestFocus). */
+    requestFocus: (nodeId: number) => void;
+    /** Callback when AT focus leaves a semantic node. */
+    clearFocus: () => void;
+    /**
+     * When false (default), the overlay only moves focus while focus is already
+     * inside Rive (overlay or canvas); when true it may also pull focus from outside Rive.
+     */
+    allowFocusInterrupt?: boolean;
+}
+/**
+ * Indication of what changed since the last overlay update.
+ *
+ * - `semanticChanged` — semantic tree content/structure changed; attributes,
+ *   DOM order, and stale removal need reconciling.
+ * - `nodeGeometryChanged` — node bounds changed in the tree model.
+ * - `layoutChanged` — canvas size/position changed (or the transform container
+ *   hasn't been created yet); the artboard→canvas transform must be recomputed.
+ */
+export interface OverlayChange {
+    semanticChanged: boolean;
+    nodeGeometryChanged: boolean;
+    layoutChanged: boolean;
+}
+/**
+ * Creates and manages an invisible DOM tree overlaying a Rive canvas. This is for
+ * screen readers to discover and interact with the Rive content.
+ *
+ * Each semantic node in the {@link SemanticTreeModel} gets a corresponding
+ * DOM element with appropriate ARIA role, states, and action handlers so
+ * assistive technologies (i.e. screen readers) can discover
+ * and interact with the Rive content.
+ *
+ * Each node receives a prefixed ID (`id=rive-{instanceId}-sem-{nodeId}`) to avoid host-page ID collisions.
+ * The nodeID is Rive's semantic node ID from core runtime.
+ * Each node is styled with `pointer-events: none`. Interactive nodes can receive
+ * programmatic focus and keydown events without entering the browser Tab order.
+ */
+export declare class AccessibilityOverlay {
+    private container;
+    private canvas;
+    private semanticsOptions;
+    private elements;
+    /** Visually-hidden description spans keyed by node ID, referenced by aria-describedby. */
+    private descElements;
+    private instanceId;
+    private fireAction;
+    private requestFocus;
+    private clearFocus;
+    private lastSemanticVersion;
+    private lastGeometryVersion;
+    /** Text elements whose fit-scale needs recomputing, batched per update (see flushTextGeometry). */
+    private pendingTextGeometry;
+    /** Last measured box-size|text key per text element, to skip redundant re-measures. */
+    private textGeometryKeys;
+    private lastCanvasPositioning;
+    /**
+     * Set when a ResizeObserver/window-resize signals the canvas geometry may have
+     * changed, cleared once the transform is re-synced. Lets {@link needsUpdate}
+     * report geometry changes without a per-frame `getBoundingClientRect()` reflow.
+     * Starts true so the first update computes the transform.
+     */
+    private _geometryDirty;
+    /** True while reconciling the DOM (reserved for future focus-sync guards). */
+    private isUpdating;
+    /** See {@link AccessibilityOverlayOptions.allowFocusInterrupt}. */
+    private allowFocusInterrupt;
+    /**
+     * Single child div of the overlay container that carries the artboard→CSS
+     * transform. All semantic node elements are children of this div and express
+     * their positions in raw artboard-space coordinates. The CSS transform on
+     * this container maps artboard units to CSS pixels in one GPU pass — no
+     * per-node matrix multiplication required.
+     */
+    private transformContainer;
+    private _artboardBounds;
+    private repositionTimer;
+    private canvasResizeObserver;
+    private parentResizeObserver;
+    /**
+     * Detects canvas *position* drift. See {@link observePosition}.
+     */
+    private positionObserver;
+    private readonly _onWindowResize;
+    constructor(options: AccessibilityOverlayOptions);
+    getSemanticOverlayContainer(): HTMLDivElement;
+    private attachPositionObservers;
+    /**
+     * Arms an IntersectionObserver whose root box is bounded to the canvas, so it
+     * fires when the canvas moves relative to the viewport — position drift that
+     * no ResizeObserver reports. Lets us re-sync the overlay container on a move
+     * instead of recalculating the canvas bounding box every frame.
+     */
+    private observePosition;
+    private scheduleReposition;
+    private syncContainerGeometry;
+    private createContainer;
+    /**
+     * Returns what changed since the last update, or null if nothing changed.
+     *
+     * Callers use this to avoid recomputing the (relatively expensive)
+     * artboard→canvas transform on frames where only node bounds changed in the
+     * tree: the transform only needs recomputing when `layoutChanged` is true.
+     */
+    needsUpdate(tree: SemanticTreeModel): OverlayChange | null;
+    /**
+     * Update the overlay DOM to reflect the current state of the semantic tree.
+     * Call once per frame after `applyDiff` when {@link needsUpdate} reports a
+     * change, when layout/transform inputs are dirty, or when a fresh
+     * `forwardMat` is supplied (even if the tree versions are unchanged).
+     *
+     * @param tree           The in-memory semantic tree model
+     * @param forwardMat     Artboard→canvas-pixel transform from `computeAlignment`,
+     *                       or null to reuse the existing CSS transform on the
+     *                       transform container
+     * @param dpr            Device pixel ratio used for the canvas backing store
+     * @param artboardBounds The artboard's own bounding rectangle
+     */
+    update(tree: SemanticTreeModel, forwardMat: rc.Mat2D | null, dpr: number, artboardBounds: rc.AABB, change?: OverlayChange | null): void;
+    private performUpdate;
+    /** Remove the overlay from the DOM entirely. */
+    destroy(): void;
+    /**
+     * Reconcile a parent DOM element's children with an ordered list of
+     * semantic node IDs. Creates, updates, and reorders elements as needed.
+     *
+     * Node positions are expressed in artboard-space coordinates. The CSS
+     * transform on the transform container maps artboard units to CSS pixels,
+     * so no per-node matrix multiplication is required here.
+     *
+     * @param parentArtboardLeft  Absolute artboard minX of the parent node (0 for roots)
+     * @param parentArtboardTop   Absolute artboard minY of the parent node (0 for roots)
+     */
+    private rebuildChildren;
+    /**
+     * Reposition only the subtrees whose bounds changed in the latest diff.
+     * Descendants are included because node CSS positions are parent-relative.
+     */
+    private updateGeometryForChangedNodes;
+    private updateNodeGeometrySubtree;
+    /**
+     * Whether the overlay may move focus now. Following focus already inside this
+     * instance is always allowed; pulling it in from the host page is gated behind
+     * allowFocusInterrupt (from the Rive class).
+     */
+    private canMoveFocus;
+    /**
+     * Move focus into a newly appeared modal/alert dialog so screen readers
+     * announce and read its content (web ATs don't auto-enter a freshly mounted
+     * dialog). Skips when focus can't move (see canMoveFocus) or a descendant
+     * already holds it. The dialog's aria-modal keeps focus trapped inside.
+     */
+    private autoFocusDialogOnAppear;
+    /**
+     * Resolve the element assistive technologies (AT) should focus on appearance. Walks the subtree
+     * depth-first and returns the first focusable node's host element, else the
+     * inner <span> of the first labeled leaf. Container and unlabeled nodes are
+     * descended into but never focused. Returns null if nothing qualifies.
+     */
+    private routeDefaultFocusTarget;
+    /** Shared `id` prefix for all semantic node elements of this instance. */
+    private get nodeIdPrefix();
+    /** Recover the semantic node ID from an overlay element, or null. */
+    private nodeIdFromElement;
+    private createElement;
+    /**
+     * Wire arrow-key roving focus for a group member (tab, radio). Arrow keys
+     * move focus to the next/previous member (wrapping), optionally Home/End jump
+     * to first/last, and the newly focused member receives a tap action.
+     */
+    private attachRovingNav;
+    private attachActionHandlers;
+    private applyAttributes;
+    /**
+     * Positions an element in artboard-space coordinates relative to its parent.
+     *
+     * Node bounds stay in raw artboard units — the CSS `transform: matrix(...)`
+     * on the transform container maps artboard units to CSS pixels in one GPU
+     * pass. No per-node forwardMat multiplication or DPR division needed here.
+     *
+     * Round to whole artboard units before comparing to avoid triggering AX
+     * layout notifications from sub-unit floating-point animation jitter.
+     */
+    private applyPosition;
+    /**
+     * Scale each queued text span to fit its layout box, batched so a frame
+     * pays at most one synchronous layout: all measurement-reset writes first,
+     * then all rect reads, then all transform writes. Interleaving
+     * write→read→write per node would force a reflow per text node instead.
+     *
+     * Nodes whose box size and text are unchanged since the last pass are
+     * skipped entirely (their existing transform is still correct — the scale
+     * is a ratio of two rects, so ancestor transform changes cancel out).
+     */
+    private flushTextGeometry;
+    /**
+     * Creates (on first call) and updates the artboard-space transform container.
+     *
+     * The container is sized to the artboard dimensions and carries a CSS
+     * `transform: matrix(...)` equivalent to `forwardMat / dpr`. All semantic
+     * node elements are children of this container and use raw artboard
+     * coordinates as their CSS `left/top/width/height`, so the CSS compositor
+     * applies the artboard→screen mapping in one pass.
+     */
+    private syncTransformContainer;
+}

package/semantics/index.d.ts

@@ -0,0 +1,5 @@
+export { SemanticTreeModel } from "./semanticTreeModel";
+export { AccessibilityOverlay } from "./accessibilityOverlay";
+export type { AccessibilityOverlayOptions } from "./accessibilityOverlay";
+export { SemanticRole, SemanticState, SemanticTrait, SemanticActionType, SemanticMode, hasState, hasTrait, roleName, stateNames, traitNames, } from "./types";
+export type { SemanticsDiffNode, SemanticsDiff, SemanticNodeData, RiveSemanticsOptions, } from "./types";

package/semantics/semanticTreeModel.d.ts

@@ -0,0 +1,64 @@
+import type { SemanticsDiff, SemanticNodeData } from "./types";
+/**
+ * Maintains an in-memory semantic tree built from incremental
+ * {@link SemanticsDiff} updates received each frame from the WASM runtime.
+ *
+ * Processing order within {@link applyDiff} follows the contract defined in
+ * `semantic_snapshot.hpp`: removed → added → moved → childrenUpdated →
+ * updatedSemantic → updatedGeometry.
+ */
+export declare class SemanticTreeModel {
+    private _nodesById;
+    private _roots;
+    private _semanticVersion;
+    private _geometryVersion;
+    private _geometryChangedIds;
+    private _semanticChangedIds;
+    get nodeCount(): number;
+    /** Bumped when semantic content or tree structure changes. */
+    get semanticVersion(): number;
+    /** Bumped when node bounds change without a semantic/structural change. */
+    get geometryVersion(): number;
+    /** Node IDs whose bounds changed in the most recent {@link applyDiff}. */
+    get geometryChangedIds(): ReadonlySet<number>;
+    /**
+     * Node IDs whose semantic fields (role/label/value/hint/flags/headingLevel)
+     * changed in the most recent {@link applyDiff}. Structural changes (moves,
+     * child reorders, removals) bump {@link semanticVersion} but don't mark
+     * nodes here — element attributes don't depend on tree position.
+     */
+    get semanticChangedIds(): ReadonlySet<number>;
+    /** Root node IDs in sibling order. */
+    get roots(): readonly number[];
+    /** Look up a node by its ID, or undefined if not in the tree. */
+    nodeById(id: number): SemanticNodeData | undefined;
+    /** Current index of a node among its siblings (or roots), or -1 if absent. */
+    private siblingIndexOf;
+    /** Detach a node from its current parent (or from roots). */
+    private detach;
+    /** Attach a node under a parent at a given sibling index (or as root). */
+    private attach;
+    /** Recursively remove a node and all descendants. */
+    private removeSubtree;
+    /**
+     * Apply an incremental diff to the tree. Bumps version counters and notifies
+     * listeners only when the tree actually changed.
+     *
+     * No-op diffs (field values identical to current model) do not bump
+     * versions — the native side guards against emitting these, but applyDiff
+     * defends its subscribers regardless.
+     */
+    applyDiff(diff: SemanticsDiff): void;
+    private _debug;
+    /** Enable/disable debug logging of diffs to the console. */
+    set debug(enabled: boolean);
+    private logDiff;
+    /**
+     * Returns every node in depth-first order, paired with its depth level.
+     * Useful for debug logging / rendering a flat list.
+     */
+    flattened(): Array<{
+        depth: number;
+        node: SemanticNodeData;
+    }>;
+}

package/semantics/types.d.ts

@@ -0,0 +1,94 @@
+import type { SemanticsDiffNode, SemanticsDiff } from "../rive_advanced.mjs";
+export type { SemanticsDiffNode, SemanticsDiff, };
+export declare const SemanticRole: {
+    readonly none: 0;
+    readonly button: 1;
+    readonly link: 2;
+    readonly checkbox: 3;
+    readonly switchControl: 4;
+    readonly slider: 5;
+    readonly textField: 6;
+    readonly text: 7;
+    readonly image: 8;
+    readonly group: 9;
+    readonly list: 10;
+    readonly listItem: 11;
+    readonly tab: 12;
+    readonly tabList: 13;
+    readonly dialog: 14;
+    readonly alertDialog: 15;
+    readonly radioGroup: 16;
+    readonly radioButton: 17;
+};
+export type SemanticRole = (typeof SemanticRole)[keyof typeof SemanticRole];
+export declare const SemanticState: {
+    readonly None: 0;
+    readonly Expanded: number;
+    readonly Selected: number;
+    readonly Checked: number;
+    readonly Mixed: number;
+    readonly Toggled: number;
+    readonly Required: number;
+    readonly Disabled: number;
+    readonly Focused: number;
+    readonly Hidden: number;
+    readonly LiveRegion: number;
+    readonly ReadOnly: number;
+    readonly Modal: number;
+    readonly Obscured: number;
+    readonly Multiline: number;
+};
+export declare function hasState(flags: number, state: number): boolean;
+/**
+ * Controls when the instance builds semantic trees and accessibility overlays.
+ *
+ * - `disabled`: no semantics work.
+ * - `enabled`: semantics and overlay are active immediately after load.
+ */
+export declare const SemanticMode: {
+    readonly Disabled: "disabled";
+    readonly Enabled: "enabled";
+};
+export type SemanticMode = (typeof SemanticMode)[keyof typeof SemanticMode];
+export interface RiveSemanticsOptions {
+    /**
+     * aria-label for the semantic DOM container element
+     */
+    riveCanvasLabel?: string;
+}
+export declare const SemanticTrait: {
+    readonly None: 0;
+    readonly Expandable: number;
+    readonly Selectable: number;
+    readonly Checkable: number;
+    readonly Toggleable: number;
+    readonly Requirable: number;
+    readonly Enablable: number;
+    readonly Focusable: number;
+};
+export declare function hasTrait(flags: number, trait: number): boolean;
+export declare const SemanticActionType: {
+    readonly tap: 0;
+    readonly increase: 1;
+    readonly decrease: 2;
+};
+export type SemanticActionType = (typeof SemanticActionType)[keyof typeof SemanticActionType];
+export interface SemanticNodeData {
+    readonly id: number;
+    parentId: number;
+    role: number;
+    label: string;
+    value: string;
+    hint: string;
+    stateFlags: number;
+    traitFlags: number;
+    headingLevel: number;
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    children: number[];
+}
+export declare function roleName(role: number): string;
+export declare function stateNames(flags: number): string;
+export declare function traitNames(flags: number): string;