HosannaViewAnimator

What is HosannaViewAnimator?

HosannaViewAnimator is a powerful view-level animation system. You provide an AnimationSpec describing logical state fields to animate on specific views, and the animator resolves the most efficient renderer fields to drive the animation. It then animates the renderers and persists the final logical state back to the views when complete.

You can use it via either:

• HosannaViewAnimator.animateViews(root, anims, duration) (static)
• BaseView.animateViews(anims, duration) (instance shortcut)

Spec format

type AnimationSpec = {
  [viewId: string]: { [stateField: string]: unknown };
};

// Example
{
  newAnimationButton: { labelOpacity: 0.0, scale: [1.0, 1.0] },
  button1: { labelOpacity: 0.0, backgroundColor: '#999999' },
  animatedRectangle1: { scale: [1.0, 1.0], color: '#999999' }
}

Tip: Start Small

Animate a couple of logical fields first, verify mappings, then scale up to more views.

How it resolves fields efficiently

HosannaViewAnimator maps each logical state field to concrete renderer fields using getAnimationPropsForStateProperty on each view. Implement this to direct a logical field to a subview’s specific renderer/field, or fall back to the view’s renderer.

Resolution Order

For each logical field, the animator asks the view for renderer bindings via getAnimationPropsForStateProperty(field). If not provided, it falls back to the view’s own renderer.

Entry points (summary)

• Static: HosannaViewAnimator.animateViews(root, anims, duration)
• Instance: BaseView.animateViews(anims, duration)

Or from any view:

  /**
   * Convenience: animate logical properties across this view's subtree.
   */
  animateViews(anims: AnimationSpec, duration: number): HosannaViewAnimator {
    return HosannaViewAnimator.animateViews(this as unknown as BaseView<ViewState>, anims, duration);
  }

Sequence

Tips

• Implement getAnimationPropsForStateProperty on custom views to precisely map logical fields to sub-renderers.
• Animations automatically stop any in-progress animation targeting the same logical view to avoid conflicts.
• On completion, logical state is persisted to the original views for consistency.

Behavioral notes:

• The animator starts from current renderer values (for smooth transitions) and persists final logical state on completion.
• If a target view already has an active animation, it is stopped before starting a new one.

Caution: Don’t Mutate During Tick

Avoid setting logical state mid-tick; let the animator handle renderer updates and final state persistence.